llm_cost_tracker 0.1.4 → 0.2.0.alpha2

data/app/views/llm_cost_tracker/tags/show.html.erb

@@ -0,0 +1,69 @@
+<section class="lct-panel">
+  <p class="lct-muted"><%= link_to "← All tag keys", tags_path %></p>
+  <h2 class="lct-section-title">Tag key: <code class="lct-code"><%= @tag_key %></code></h2>
+  <% if @total_calls.positive? %>
+    <p class="lct-muted">
+      <%= number(@tagged_calls) %> of <%= number(@total_calls) %> calls have this key
+      (<%= percent(coverage_percent(@tagged_calls, @total_calls)) %> coverage) &middot;
+      <%= number(@distinct_values) %> distinct <%= @distinct_values == 1 ? "value" : "values" %>
+    </p>
+  <% end %>
+  <form class="lct-filters" action="<%= tag_path(@tag_key) %>" method="get">
+    <div class="lct-field">
+      <label for="lct-from">From</label>
+      <input id="lct-from" type="date" name="from" value="<%= params[:from] %>">
+    </div>
+
+    <div class="lct-field">
+      <label for="lct-to">To</label>
+      <input id="lct-to" type="date" name="to" value="<%= params[:to] %>">
+    </div>
+
+    <div class="lct-field">
+      <label for="lct-provider">Provider</label>
+      <input id="lct-provider" type="text" name="provider" value="<%= params[:provider] %>">
+    </div>
+
+    <div class="lct-field">
+      <label for="lct-model">Model</label>
+      <input id="lct-model" type="text" name="model" value="<%= params[:model] %>">
+    </div>
+
+    <div class="lct-button-row">
+      <button class="lct-button" type="submit">Apply</button>
+      <%= link_to "Reset", tag_path(@tag_key), class: "lct-button lct-button-secondary" %>
+    </div>
+  </form>
+</section>
+
+<% if @rows.empty? %>
+  <section class="lct-panel lct-empty">
+    <h2 class="lct-section-title">No calls tagged with <%= @tag_key %></h2>
+    <p class="lct-muted">Calls carrying this tag will appear here when they match the current filters.</p>
+  </section>
+<% else %>
+  <section class="lct-panel">
+    <div class="lct-table-wrap">
+      <table class="lct-table">
+        <thead>
+          <tr>
+            <th>Value</th>
+            <th>Calls</th>
+            <th>Total cost</th>
+            <th>Avg cost / call</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @rows.each do |row| %>
+            <tr>
+              <td><%= row.value %></td>
+              <td><%= number(row.calls) %></td>
+              <td><%= money(row.total_cost) %></td>
+              <td><%= money(row.average_cost_per_call) %></td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  </section>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+LlmCostTracker::Engine.routes.draw do
+  root "dashboard#index"
+  resources :calls, only: %i[index show], constraints: { id: /\d+/ }, defaults: { format: :html }
+  resources :models, only: :index
+  get "tags",      to: "tags#index",  as: :tags
+  get "tags/:key", to: "tags#show",   as: :tag, format: false
+  get "data_quality", to: "data_quality#index", as: :data_quality
+end

data/lib/llm_cost_tracker/budget.rb

@@ -4,17 +4,15 @@ require_relative "logging"
 
 module LlmCostTracker
   class Budget
-    WARNING_MUTEX = Mutex.new
-    private_constant :WARNING_MUTEX
-
     class << self
       def enforce!
-        return unless LlmCostTracker.configuration.monthly_budget
-        return unless behavior == :block_requests
-        return warn_non_active_record_block_requests unless LlmCostTracker.configuration.active_record?
+        config = LlmCostTracker.configuration
+        return unless config.monthly_budget
+        return unless config.budget_exceeded_behavior == :block_requests
+        return unless config.active_record?
 
-        monthly_total = calculate_monthly_total(0)
-        return unless monthly_total >= LlmCostTracker.configuration.monthly_budget
+        monthly_total = active_record_monthly_total
+        return unless monthly_total >= config.monthly_budget
 
         handle_exceeded(monthly_total: monthly_total)
       end
@@ -22,24 +20,20 @@ module LlmCostTracker
       def check!(event)
         config = LlmCostTracker.configuration
         return unless config.monthly_budget
-        return unless event[:cost]
+        return unless event.cost
 
-        monthly_total = calculate_monthly_total(event[:cost][:total_cost])
-        return unless monthly_total > config.monthly_budget
+        monthly_total = if config.active_record?
+                          active_record_monthly_total
+                        else
+                          event.cost.total_cost
+                        end
+        return unless monthly_total >= config.monthly_budget
 
         handle_exceeded(monthly_total: monthly_total, last_event: event)
       end
 
       private
 
-      def calculate_monthly_total(latest_cost)
-        if LlmCostTracker.configuration.active_record?
-          active_record_monthly_total
-        else
-          latest_cost
-        end
-      end
-
       def active_record_monthly_total
         require_relative "llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
         require_relative "storage/active_record_store" unless defined?(LlmCostTracker::Storage::ActiveRecordStore)
@@ -49,18 +43,6 @@ module LlmCostTracker
         raise Error, "ActiveRecord storage requires the active_record gem: #{e.message}"
       end
 
-      def warn_non_active_record_block_requests
-        should_warn = WARNING_MUTEX.synchronize do
-          unless @warned_non_active_record_block_requests
-            @warned_non_active_record_block_requests = true
-            true
-          end
-        end
-        return unless should_warn
-
-        Logging.warn(":block_requests preflight requires storage_backend = :active_record; request was not blocked.")
-      end
-
       def handle_exceeded(monthly_total:, last_event: nil)
         config = LlmCostTracker.configuration
         payload = {
@@ -70,15 +52,11 @@ module LlmCostTracker
         }
 
         config.on_budget_exceeded&.call(payload)
-        raise BudgetExceededError.new(**payload) if raise_on_exceeded?
-      end
-
-      def raise_on_exceeded?
-        %i[raise block_requests].include?(behavior)
+        raise BudgetExceededError.new(**payload) if raise_on_exceeded?(config)
       end
 
-      def behavior
-        LlmCostTracker.configuration.budget_exceeded_behavior
+      def raise_on_exceeded?(config)
+        %i[raise block_requests].include?(config.budget_exceeded_behavior)
       end
     end
   end

data/lib/llm_cost_tracker/configuration.rb

@@ -22,7 +22,8 @@ module LlmCostTracker
                   :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
+                  :pricing_overrides,  # Hash to override built-in pricing
+                  :report_tag_breakdowns # Array of tag keys to break down in the rake report
 
     attr_reader :budget_exceeded_behavior, # :notify, :raise, :block_requests
                 :storage_backend, # :log, :active_record, :custom
@@ -43,6 +44,7 @@ module LlmCostTracker
       @log_level          = :info
       @prices_file        = nil
       @pricing_overrides  = {}
+      @report_tag_breakdowns = []
       self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
     end
 

data/lib/llm_cost_tracker/cost.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "value_object"
-
 module LlmCostTracker
-  Cost = ValueObject.define(
+  Cost = Data.define(
     :input_cost,
     :cached_input_cost,
     :cache_read_input_cost,

data/lib/llm_cost_tracker/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails"
+require_relative "../llm_cost_tracker"
+require_relative "engine_compatibility"
+
+LlmCostTracker::EngineCompatibility.check_rails_version!(Rails.version)
+
+module LlmCostTracker
+  class Engine < ::Rails::Engine
+    isolate_namespace LlmCostTracker
+  end
+end

data/lib/llm_cost_tracker/engine_compatibility.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module EngineCompatibility
+    REQUIRED_RAILS_VERSION = Gem::Version.new("7.1.0")
+
+    class << self
+      def check_rails_version!(version)
+        return if Gem::Version.new(version) >= REQUIRED_RAILS_VERSION
+
+        raise LlmCostTracker::Error, "LlmCostTracker::Engine requires Rails 7.1+"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/errors.rb

@@ -3,6 +3,8 @@
 module LlmCostTracker
   class Error < StandardError; end
 
+  class InvalidFilterError < Error; end
+
   class BudgetExceededError < Error
     attr_reader :monthly_total, :budget, :last_event
 

data/lib/llm_cost_tracker/event.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "value_object"
-
 module LlmCostTracker
-  Event = ValueObject.define(
+  Event = Data.define(
     :provider,
     :model,
     :input_tokens,

data/lib/llm_cost_tracker/event_metadata.rb

@@ -16,22 +16,17 @@ module LlmCostTracker
 
     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)
+        metadata = metadata.to_h.symbolize_keys
+        cache_read = first_integer(metadata, :cache_read_input_tokens, :cache_read_tokens)
+        cache_creation = first_integer(metadata, :cache_creation_input_tokens, :cache_creation_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
+          cached_input_tokens: metadata[:cached_input_tokens].to_i,
+          cache_read_input_tokens: cache_read,
+          cache_creation_input_tokens: cache_creation,
+          total_tokens: input_tokens.to_i + output_tokens.to_i + cache_read + cache_creation
         }
       end
 
@@ -41,12 +36,8 @@ module LlmCostTracker
 
       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
-
+      def first_integer(metadata, *keys)
+        keys.each { |key| return metadata[key].to_i unless metadata[key].nil? }
         0
       end
     end

data/lib/llm_cost_tracker/llm_api_call.rb

@@ -2,24 +2,21 @@
 
 require "active_record"
 
+require_relative "period_grouping"
 require_relative "tag_accessors"
+require_relative "tag_key"
 require_relative "tag_query"
 require_relative "tags_column"
 
 module LlmCostTracker
   class LlmApiCall < ActiveRecord::Base
-    TAG_KEY_PATTERN = /\A[\w.-]+\z/
-
-    private_constant :TAG_KEY_PATTERN
-
+    extend PeriodGrouping
     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 :with_cost, -> { where.not(total_cost: nil) }
     scope :without_cost, -> { where(total_cost: nil) }
     scope :unknown_pricing, -> { without_cost }
@@ -92,13 +89,6 @@ module LlmCostTracker
       group(:provider).average(:latency_ms).transform_values(&:to_f)
     end
 
-    def self.daily_costs(days: 30)
-      where(tracked_at: days.days.ago..)
-        .group("DATE(tracked_at)")
-        .sum(:total_cost)
-        .transform_keys(&:to_s)
-    end
-
     def self.tag_label(value)
       value.nil? || value == "" ? "(untagged)" : value.to_s
     end
@@ -121,10 +111,7 @@ module LlmCostTracker
     private_class_method :tag_group_expression
 
     def self.validated_tag_key(key)
-      key = key.to_s
-      return key if key.match?(TAG_KEY_PATTERN)
-
-      raise ArgumentError, "invalid tag key: #{key.inspect}"
+      TagKey.validate!(key)
     end
     private_class_method :validated_tag_key
 

data/lib/llm_cost_tracker/middleware/faraday.rb

@@ -37,10 +37,10 @@ module LlmCostTracker
         return unless parsed
 
         Tracker.record(
-          provider: parsed[:provider],
-          model: parsed[:model],
-          input_tokens: parsed[:input_tokens],
-          output_tokens: parsed[:output_tokens],
+          provider: parsed.provider,
+          model: parsed.model,
+          input_tokens: parsed.input_tokens,
+          output_tokens: parsed.output_tokens,
           latency_ms: latency_ms,
           metadata: resolved_tags(request_env).merge(parsed.metadata)
         )

data/lib/llm_cost_tracker/parsed_usage.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "value_object"
-
 module LlmCostTracker
-  ParsedUsage = ValueObject.define(
+  ParsedUsage = Data.define(
     :provider,
     :model,
     :input_tokens,
@@ -15,10 +13,10 @@ module LlmCostTracker
     :reasoning_tokens
   )
 
-  ParsedUsage.const_set(:TRACKING_KEYS, %i[provider model input_tokens output_tokens total_tokens].freeze)
+  class ParsedUsage
+    TRACKING_KEYS = %i[provider model input_tokens output_tokens total_tokens].freeze
 
-  class << ParsedUsage
-    def build(**attributes)
+    def self.build(**attributes)
       new(
         provider: attributes.fetch(:provider),
         model: attributes.fetch(:model),
@@ -31,11 +29,9 @@ module LlmCostTracker
         reasoning_tokens: attributes[:reasoning_tokens]
       )
     end
-  end
 
-  class ParsedUsage
     def metadata
-      except(*TRACKING_KEYS)
+      to_h.except(*TRACKING_KEYS)
     end
 
     def to_h

data/lib/llm_cost_tracker/parsers/anthropic.rb

@@ -28,11 +28,10 @@ module LlmCostTracker
         ParsedUsage.build(
           provider: "anthropic",
           model: response["model"] || request["model"],
-          input_tokens: usage["input_tokens"] || 0,
-          output_tokens: usage["output_tokens"] || 0,
-          total_tokens: (usage["input_tokens"] || 0) + (usage["output_tokens"] || 0) +
-            (usage["cache_read_input_tokens"] || 0) +
-            (usage["cache_creation_input_tokens"] || 0),
+          input_tokens: usage["input_tokens"].to_i,
+          output_tokens: usage["output_tokens"].to_i,
+          total_tokens: usage["input_tokens"].to_i + usage["output_tokens"].to_i +
+            usage["cache_read_input_tokens"].to_i + usage["cache_creation_input_tokens"].to_i,
           cache_read_input_tokens: usage["cache_read_input_tokens"],
           cache_creation_input_tokens: usage["cache_creation_input_tokens"]
         )

data/lib/llm_cost_tracker/parsers/base.rb

@@ -5,15 +5,10 @@ require "json"
 module LlmCostTracker
   module Parsers
     class Base
-      # Returns a hash with parsed usage data, or nil if not applicable.
+      # Parse a provider response into a {LlmCostTracker::ParsedUsage}, or return
+      # nil when the response is not trackable (non-200, missing usage, etc).
       #
-      # Expected return format:
-      # {
-      #   provider: "openai",
-      #   model: "gpt-4o",
-      #   input_tokens: 150,
-      #   output_tokens: 42
-      # }
+      # @return [LlmCostTracker::ParsedUsage, nil]
       def parse(request_url, request_body, response_status, response_body)
         raise NotImplementedError
       end

data/lib/llm_cost_tracker/parsers/gemini.rb

@@ -30,9 +30,9 @@ module LlmCostTracker
         ParsedUsage.build(
           provider: "gemini",
           model: model,
-          input_tokens: usage["promptTokenCount"] || 0,
+          input_tokens: usage["promptTokenCount"].to_i,
           output_tokens: output_tokens(usage),
-          total_tokens: usage["totalTokenCount"] || 0,
+          total_tokens: usage["totalTokenCount"].to_i,
           cached_input_tokens: usage["cachedContentTokenCount"]
         )
       end
@@ -40,7 +40,7 @@ module LlmCostTracker
       private
 
       def output_tokens(usage)
-        (usage["candidatesTokenCount"] || 0) + (usage["thoughtsTokenCount"] || 0)
+        usage["candidatesTokenCount"].to_i + usage["thoughtsTokenCount"].to_i
       end
 
       def extract_model_from_url(url)

data/lib/llm_cost_tracker/parsers/openai_usage.rb

@@ -17,9 +17,9 @@ module LlmCostTracker
         ParsedUsage.build(
           provider: provider_for(request_url),
           model: response["model"] || request["model"],
-          input_tokens: usage["prompt_tokens"] || usage["input_tokens"] || 0,
-          output_tokens: usage["completion_tokens"] || usage["output_tokens"] || 0,
-          total_tokens: usage["total_tokens"] || 0,
+          input_tokens: (usage["prompt_tokens"] || usage["input_tokens"]).to_i,
+          output_tokens: (usage["completion_tokens"] || usage["output_tokens"]).to_i,
+          total_tokens: usage["total_tokens"].to_i,
           cached_input_tokens: cached_input_tokens(usage)
         )
       end

data/lib/llm_cost_tracker/parsers/registry.rb

@@ -4,33 +4,26 @@ module LlmCostTracker
   module Parsers
     class Registry
       class << self
-        PARSERS_MUTEX = Mutex.new
-
         def parsers
-          @parsers || PARSERS_MUTEX.synchronize { @parsers ||= default_parsers }
+          @parsers ||= default_parsers
         end
 
         def register(parser)
-          PARSERS_MUTEX.synchronize { parsers.unshift(parser) }
+          parsers.unshift(parser)
         end
 
         def find_for(url)
-          parsers.find { |p| p.match?(url) }
+          parsers.find { |parser| parser.match?(url) }
         end
 
         def reset!
-          PARSERS_MUTEX.synchronize { @parsers = nil }
+          @parsers = nil
         end
 
         private
 
         def default_parsers
-          [
-            Openai.new,
-            OpenaiCompatible.new,
-            Anthropic.new,
-            Gemini.new
-          ]
+          [Openai.new, OpenaiCompatible.new, Anthropic.new, Gemini.new]
         end
       end
     end

data/lib/llm_cost_tracker/period_grouping.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module PeriodGrouping
+    PERIOD_FORMATS = {
+      day: {
+        postgres: "YYYY-MM-DD",
+        mysql: "%Y-%m-%d",
+        sqlite: "%Y-%m-%d"
+      },
+      month: {
+        postgres: "YYYY-MM",
+        mysql: "%Y-%m",
+        sqlite: "%Y-%m"
+      }
+    }.freeze
+
+    private_constant :PERIOD_FORMATS
+
+    def group_by_period(period, column: :tracked_at)
+      group(Arel.sql(period_group_expression(period, column: column)))
+    end
+
+    def daily_costs(days: 30)
+      where(tracked_at: days.days.ago..)
+        .group_by_period(:day)
+        .sum(:total_cost)
+    end
+
+    private
+
+    def period_group_expression(period, column:)
+      period = validated_period(period)
+      column = period_column_expression(column)
+      formats = PERIOD_FORMATS.fetch(period)
+
+      case connection.adapter_name
+      when /postgres/i
+        postgres_period_expression(period, column, formats)
+      when /mysql/i
+        "DATE_FORMAT(#{column}, #{connection.quote(formats.fetch(:mysql))})"
+      else
+        "strftime(#{connection.quote(formats.fetch(:sqlite))}, #{column})"
+      end
+    end
+
+    def postgres_period_expression(period, column, formats)
+      "TO_CHAR(" \
+        "DATE_TRUNC(#{connection.quote(period.to_s)}, #{column}), " \
+        "#{connection.quote(formats.fetch(:postgres))}" \
+        ")"
+    end
+
+    def validated_period(period)
+      normalized_period = period.respond_to?(:to_sym) ? period.to_sym : nil
+      return normalized_period if PERIOD_FORMATS.key?(normalized_period)
+
+      raise ArgumentError, "invalid period: #{period.inspect}"
+    end
+
+    def period_column_expression(column)
+      column = column.to_s
+      return "#{quoted_table_name}.#{connection.quote_column_name(column)}" if column_names.include?(column)
+
+      raise ArgumentError, "invalid period column: #{column.inspect}"
+    end
+  end
+end