llm_cost_tracker 0.13.0 → 0.14.1

data/app/services/llm_cost_tracker/dashboard/filter.rb

@@ -5,20 +5,23 @@ require "date"
 module LlmCostTracker
   module Dashboard
     class Filter
+      MAX_TAG_FILTERS = 10
+      MATCH_NOTHING = Arel.sql("1 = 0")
       STREAM_FILTER_OPTIONS = [
         ["Streaming only", "yes"],
         ["Non-streaming only", "no"]
       ].freeze
 
       class << self
-        def call(scope: LlmCostTracker::Call.all, params: {})
-          new(scope: scope, params: params).relation
+        def call(scope: LlmCostTracker::Call.all, params: {}, tags: {})
+          new(scope: scope, params: params, tags: tags).relation
         end
       end
 
-      def initialize(scope:, params:)
+      def initialize(scope:, params:, tags: {})
         @scope = scope
         @params = LlmCostTracker::Dashboard::Params.to_hash(params).symbolize_keys
+        @extra_tags = tags
       end
 
       def relation
@@ -27,13 +30,13 @@ module LlmCostTracker
         filtered_scope = apply_exact_filter(filtered_scope, :provider)
         filtered_scope = apply_exact_filter(filtered_scope, :model)
         filtered_scope = apply_stream_filter(filtered_scope)
-        filtered_scope = apply_usage_source_filter(filtered_scope)
+        filtered_scope = apply_exact_filter(filtered_scope, :usage_source)
         apply_tag_filters(filtered_scope)
       end
 
       private
 
-      attr_reader :scope, :params
+      attr_reader :scope, :params, :extra_tags
 
       def apply_date_filters(relation)
         from_date = Dashboard::DateRange.parse(params, :from)
@@ -50,21 +53,25 @@ module LlmCostTracker
       end
 
       def apply_exact_filter(relation, key)
-        value = normalized_string(params[key])
+        value = normalized_string(params[key], key)
         return relation if value.nil?
 
-        relation.where(key => value)
+        matchable?([value]) ? relation.where(key => value) : relation.where(MATCH_NOTHING)
       end
 
       def apply_tag_filters(relation)
-        tags = tag_params
+        tags = tag_params.merge(extra_tags)
         return relation if tags.empty?
+        if tags.size > MAX_TAG_FILTERS
+          raise LlmCostTracker::InvalidFilterError,
+                "at most #{MAX_TAG_FILTERS} tag filters are allowed, got #{tags.size}"
+        end
 
-        relation.by_tags(tags)
+        matchable?(tags.values) ? relation.by_tags(tags) : relation.where(MATCH_NOTHING)
       end
 
       def apply_stream_filter(relation)
-        value = normalized_string(params[:stream])
+        value = normalized_string(params[:stream], :stream)
         return relation if value.nil?
 
         case value.downcase
@@ -74,28 +81,24 @@ module LlmCostTracker
         end
       end
 
-      def apply_usage_source_filter(relation)
-        value = normalized_string(params[:usage_source])
-        return relation if value.nil?
-
-        relation.where(usage_source: value)
-      end
-
       def tag_params
         tags = LlmCostTracker::Dashboard::Params.to_hash(params[:tag])
 
         tags.each_with_object({}) do |(key, value), normalized|
-          value = normalized_string(value)
+          value = normalized_string(value, "tag filter value")
           next if value.nil?
 
           normalized[LlmCostTracker::Tags::Key.validate!(key, error_class: LlmCostTracker::InvalidFilterError)] = value
         end
       end
 
-      def normalized_string(value)
-        return nil if value.nil?
+      def matchable?(values)
+        values.none? { |value| value.include?("\0") } ||
+          !LlmCostTracker::Ledger::Schema::Adapter.postgresql?(scope.connection)
+      end
 
-        value.to_s.strip.presence
+      def normalized_string(value, name)
+        LlmCostTracker::Dashboard::Params.scalar(value, name).strip.presence
       end
     end
   end

data/app/services/llm_cost_tracker/dashboard/monthly_budget.rb

@@ -6,7 +6,7 @@ module LlmCostTracker
       module_function
 
       def status
-        budget = LlmCostTracker.configuration.monthly_budget
+        budget = LlmCostTracker.configuration.budgets.monthly
         return nil unless budget
 
         budget = budget.to_f

data/app/services/llm_cost_tracker/dashboard/pagination.rb

@@ -6,6 +6,7 @@ module LlmCostTracker
       DEFAULT_PER = 50
       MAX_PER = 200
       MIN_PAGE = 1
+      MAX_PAGE = 100_000
       MIN_PER = 1
 
       attr_reader :page, :per
@@ -13,7 +14,7 @@ module LlmCostTracker
       def self.call(params)
         params = Params.to_hash(params).symbolize_keys
         new(
-          page: integer_param(params, :page, default: MIN_PAGE, min: MIN_PAGE),
+          page: integer_param(params, :page, default: MIN_PAGE, min: MIN_PAGE, max: MAX_PAGE),
           per: integer_param(params, :per, default: DEFAULT_PER, min: MIN_PER, max: MAX_PER)
         )
       end

data/app/services/llm_cost_tracker/dashboard/params.rb

@@ -3,6 +3,8 @@
 module LlmCostTracker
   module Dashboard
     module Params
+      QUERY_KEYS = %i[from to provider model tag tag_value stream usage_source cost_status sort dir page per].freeze
+
       class << self
         def to_hash(value)
           return {} if value.nil?
@@ -17,6 +19,14 @@ module LlmCostTracker
           {}
         end
 
+        def scalar(value, name)
+          if value.is_a?(Hash) || value.is_a?(Array) || value.respond_to?(:to_unsafe_h)
+            raise InvalidFilterError, "#{name} must be a single value"
+          end
+
+          value.to_s
+        end
+
         def tag_query(value)
           to_hash(value).each_with_object({}) do |(key, tag_value), tags|
             key = key.to_s

data/app/services/llm_cost_tracker/dashboard/pricing_overview.rb

@@ -46,8 +46,8 @@ module LlmCostTracker
 
       def subtitle_for(key)
         case key
-        when :overrides then "config.pricing_overrides"
-        when :file then LlmCostTracker.configuration.prices_file.to_s
+        when :overrides then "config.pricing.overrides"
+        when :file then LlmCostTracker.configuration.pricing.file.to_s
         when :bundled then "ships with the gem"
         end
       end
@@ -55,7 +55,7 @@ module LlmCostTracker
       def updated_at_for(key)
         case key
         when :file
-          path = LlmCostTracker.configuration.prices_file
+          path = LlmCostTracker.configuration.pricing.file
           Pricing::Registry.file_metadata(path)["updated_at"] || Pricing::Registry.prices_file_mtime_iso
         when :bundled
           Pricing::Registry.metadata["updated_at"]

data/app/services/llm_cost_tracker/dashboard/setup_state.rb

@@ -7,13 +7,15 @@ module LlmCostTracker
 
       class << self
         def current
-          return @current if defined?(@current)
+          return if @healthy
 
-          @current = compute
+          state = compute
+          @healthy = state.nil?
+          state
         end
 
         def reset!
-          remove_instance_variable(:@current) if defined?(@current)
+          @healthy = false
         end
 
         private

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

@@ -2,7 +2,7 @@
 <% line_item_costs_by_component = call_line_item_costs_by_component(@call) %>
 <% token_segments = priced_components.map do |component|
   token_key = component.fetch(:token_key)
-  value = @call.has_attribute?(token_key) ? @call[token_key] : 0
+  value = @call[token_key]
   { label: component.fetch(:label), value: value, formatted_value: number_with_delimiter(value), css_class: component.fetch(:css_class) }
 end %>
 <% cost_segments = [] %>
@@ -68,13 +68,11 @@ end %>
       <dt>Batch</dt>
       <dd><%= @call.batch? ? "yes" : "no" %></dd>
     </div>
-    <% if @call.has_attribute?(:stream) %>
-      <div class="lct-meta-strip-item">
-        <dt>Stream</dt>
-        <dd><%= @call.stream? ? "yes" : "no" %></dd>
-      </div>
-    <% end %>
-    <% if @call.has_attribute?(:usage_source) && @call.usage_source.present? %>
+    <div class="lct-meta-strip-item">
+      <dt>Stream</dt>
+      <dd><%= @call.stream? ? "yes" : "no" %></dd>
+    </div>
+    <% if @call.usage_source.present? %>
       <div class="lct-meta-strip-item">
         <dt>Usage source</dt>
         <dd><code class="lct-code-id"><%= @call.usage_source %></code></dd>

data/app/views/llm_cost_tracker/data_quality/index.html.erb

@@ -21,6 +21,17 @@
   </div>
 <% end %>
 
+<% if @unseen_budget_tags %>
+  <h3 class="lct-stat-section-label">Budgets</h3>
+  <div class="lct-stat-grid">
+    <div class="lct-stat lct-stat-warn">
+      <div class="lct-stat-head"><p class="lct-stat-label">Budgeted tags never recorded</p></div>
+      <p class="lct-stat-value"><%= @unseen_budget_tags.keys.join(", ") %></p>
+      <p class="lct-stat-foot">No call carries <%= @unseen_budget_tags.keys.one? ? "this tag" : "these tags" %> yet, so <%= @unseen_budget_tags.keys.one? ? "its budget never fires" : "their budgets never fire" %>. Expected on a young ledger; otherwise check the name against the tags you pass.</p>
+    </div>
+  </div>
+<% end %>
+
 <% if @summary.total.zero? %>
   <section class="lct-panel lct-empty">
     <h2 class="lct-state-title">No data yet</h2>

data/app/views/llm_cost_tracker/shared/_filter_pill_date.html.erb

@@ -9,9 +9,7 @@
   </summary>
   <%= form_with url: path, method: :get, local: true, html: { class: "lct-filter-pop-body" } do %>
     <% extra_hidden.each do |k, v| %><%= hidden_field_tag k, v %><% end %>
-    <% current_query.except(:from, :to, :page, :per, *extra_except).each do |key, value| %>
-      <% Array(value).each do |v| %><%= hidden_field_tag(value.is_a?(Array) ? "#{key}[]" : key.to_s, v) %><% end %>
-    <% end %>
+    <%= hidden_query_fields(current_query.except(:from, :to, :page, :per, *extra_except)) %>
     <div class="lct-filter-pop-field"><label for="lct-filter-from">From</label><input type="date" name="from" id="lct-filter-from" value="<%= @from_date.iso8601 %>"></div>
     <div class="lct-filter-pop-field"><label for="lct-filter-to">To</label><input type="date" name="to" id="lct-filter-to" value="<%= @to_date.iso8601 %>"></div>
     <button type="submit" class="lct-button lct-button-primary">Apply</button>

data/app/views/llm_cost_tracker/shared/_filter_pill_model.html.erb

@@ -10,9 +10,7 @@
   </summary>
   <%= form_with url: path, method: :get, local: true, html: { class: "lct-filter-pop-body" } do %>
     <% extra_hidden.each do |k, v| %><%= hidden_field_tag k, v %><% end %>
-    <% current_query.except(:model, :page, :per, *extra_except).each do |key, value| %>
-      <% Array(value).each do |v| %><%= hidden_field_tag(value.is_a?(Array) ? "#{key}[]" : key.to_s, v) %><% end %>
-    <% end %>
+    <%= hidden_query_fields(current_query.except(:model, :page, :per, *extra_except)) %>
     <div class="lct-filter-pop-field">
       <label for="lct-filter-model">Model</label>
       <%= select_tag :model, options_for_select(filter_options_for(:model), active), include_blank: "All models", id: "lct-filter-model" %>

data/app/views/llm_cost_tracker/shared/_filter_pill_provider.html.erb

@@ -10,9 +10,7 @@
   </summary>
   <%= form_with url: path, method: :get, local: true, html: { class: "lct-filter-pop-body" } do %>
     <% extra_hidden.each do |k, v| %><%= hidden_field_tag k, v %><% end %>
-    <% current_query.except(:provider, :page, :per, *extra_except).each do |key, value| %>
-      <% Array(value).each do |v| %><%= hidden_field_tag(value.is_a?(Array) ? "#{key}[]" : key.to_s, v) %><% end %>
-    <% end %>
+    <%= hidden_query_fields(current_query.except(:provider, :page, :per, *extra_except)) %>
     <div class="lct-filter-pop-field">
       <label for="lct-filter-provider">Provider</label>
       <%= select_tag :provider, options_for_select(filter_options_for(:provider), active), include_blank: "All providers", id: "lct-filter-provider" %>

data/app/views/llm_cost_tracker/shared/_filter_pill_stream.html.erb

@@ -11,9 +11,7 @@
   </summary>
   <%= form_with url: path, method: :get, local: true, html: { class: "lct-filter-pop-body" } do %>
     <% extra_hidden.each do |k, v| %><%= hidden_field_tag k, v %><% end %>
-    <% current_query.except(:stream, :page, :per, *extra_except).each do |key, value| %>
-      <% Array(value).each do |v| %><%= hidden_field_tag(value.is_a?(Array) ? "#{key}[]" : key.to_s, v) %><% end %>
-    <% end %>
+    <%= hidden_query_fields(current_query.except(:stream, :page, :per, *extra_except)) %>
     <div class="lct-filter-pop-field">
       <label for="lct-filter-stream">Stream</label>
       <%= select_tag :stream, options_for_select(LlmCostTracker::Dashboard::Filter::STREAM_FILTER_OPTIONS, active), include_blank: "All calls", id: "lct-filter-stream" %>

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

@@ -107,6 +107,7 @@
           </tr>
         </thead>
         <tbody>
+          <% drilldown_allowed = tag_drilldown_allowed?(params[:key]) %>
           <% @breakdown.rows.each do |row| %>
             <tr>
               <td><code class="lct-code-id"><%= row.value %></code></td>
@@ -117,6 +118,8 @@
               <td class="lct-num">
                 <% if row.value == "(untagged)" %>
                   <span class="lct-num-muted">n/a</span>
+                <% elsif !drilldown_allowed %>
+                  <span class="lct-num-muted">tag filter limit</span>
                 <% else %>
                   <%= link_to "Trend", tag_path(params[:key], current_query.merge(tag_value: row.value)), class: "lct-page-link" %>
                   <%= link_to "Calls", calls_path(calls_query_for_tag(key: params[:key], value: row.value)), class: "lct-page-link" %>

data/config/routes.rb

@@ -4,7 +4,12 @@ LlmCostTracker::Engine.routes.draw do
   root "dashboard#index"
   resources :calls, only: %i[index show], constraints: { id: /\d+/ }, defaults: { format: :html }
   resources :models, only: :index
-  resources :tags, only: %i[index show], param: :key, format: false
+  resources :tags,
+            only: %i[index show],
+            param: :key,
+            format: false,
+            constraints: { key: %r{[^/]+} },
+            defaults: { format: :html }
   get "data_quality", to: "data_quality#index", as: :data_quality
   get "pricing", to: "pricing#index", as: :pricing
 

data/lib/llm_cost_tracker/budget/per_tag.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative "../ledger/isolation"
+require_relative "../ledger/schema/adapter"
+require_relative "../ledger/tags/encoding"
+
+module LlmCostTracker
+  module Budget
+    module PerTag
+      COST_COLUMN = "total_cost"
+      TIME_COLUMN = "tracked_at"
+      WINDOW_STARTS = { daily: :beginning_of_day, weekly: :beginning_of_week, monthly: :beginning_of_month }.freeze
+      WINDOW_NEXTS = { daily: :next_day, weekly: :next_week, monthly: :next_month }.freeze
+      SLOW_READ_SECONDS = 0.1
+      DEFAULT_BACKFILL_BATCH = 5_000
+
+      Rule = Data.define(:key, :value, :windows, :behavior, :on_exceeded)
+
+      class << self
+        def configured
+          LlmCostTracker.configuration.budgets.per_tag
+        end
+
+        def active?
+          return false if configured.empty?
+          return true if columns?
+
+          warn_missing_columns
+          false
+        end
+
+        def blocking?
+          active? && configured.each_value.any? { |entry| behavior_for(entry) == :block_requests }
+        end
+
+        def rules_for(tags, blocking_only: false)
+          return [] unless active?
+
+          normalized = (tags || {}).to_h.transform_keys(&:to_s)
+          configured.filter_map do |key, entry|
+            raw = normalized[key]
+            next if raw.nil?
+            next if blocking_only && behavior_for(entry) != :block_requests
+
+            Rule.new(
+              key: key,
+              value: Ledger::Tags::Encoding.encode(raw),
+              windows: entry[:windows],
+              behavior: behavior_for(entry),
+              on_exceeded: on_exceeded_for(entry)
+            )
+          end
+        end
+
+        def rules_for_events(events)
+          events.each_with_object({}) do |event, grouped|
+            rules_for(event.tags).each { |rule| (grouped[rule] ||= []) << event }
+          end
+        end
+
+        def spend(key, value, window, time:)
+          spend_by_value(key, [value], window, window_start(window, time)).fetch(value, 0).to_d
+        end
+
+        def spend_by_value(key, values, window, bucket)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          totals = Ledger::Isolation.guard(LlmCostTracker::CallTag) do
+            LlmCostTracker::CallTag
+              .where(key: key, value: values, TIME_COLUMN => window_range(window, bucket))
+              .group(:value).sum(COST_COLUMN)
+          end
+          warn_slow_read(key, window, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at)
+          totals
+        end
+
+        def window_start(window, time)
+          time.to_time.utc.public_send(WINDOW_STARTS.fetch(window))
+        end
+
+        def backfill(batch_size: DEFAULT_BACKFILL_BATCH)
+          return 0 unless columns?
+
+          filled = 0
+          loop do
+            copied = copy_next_batch(batch_size)
+            break if copied.zero?
+
+            filled += copied
+          end
+          filled
+        end
+
+        def columns?
+          LlmCostTracker::CallTag.table_exists? &&
+            (LlmCostTracker::CallTag.column_names & [COST_COLUMN, TIME_COLUMN]).size == 2
+        end
+
+        private
+
+        def window_range(window, bucket)
+          bucket...bucket.public_send(WINDOW_NEXTS.fetch(window))
+        end
+
+        def copy_next_batch(batch_size)
+          ids = LlmCostTracker::CallTag.where(TIME_COLUMN => nil).limit(batch_size).pluck(:id)
+          return 0 if ids.empty?
+
+          LlmCostTracker::CallTag.connection.update(copy_sql(ids))
+        end
+
+        def copy_sql(ids)
+          tags = LlmCostTracker::CallTag.quoted_table_name
+          calls = LlmCostTracker::Call.quoted_table_name
+          list = ids.join(",")
+          return <<~SQL.squish unless Ledger::Schema::Adapter.postgresql?(LlmCostTracker::CallTag.connection)
+            UPDATE #{tags} t JOIN #{calls} c ON c.id = t.llm_cost_tracker_call_id
+               SET t.#{COST_COLUMN} = c.#{COST_COLUMN}, t.#{TIME_COLUMN} = c.#{TIME_COLUMN}
+             WHERE t.id IN (#{list})
+          SQL
+
+          <<~SQL.squish
+            UPDATE #{tags} AS t
+               SET #{COST_COLUMN} = c.#{COST_COLUMN}, #{TIME_COLUMN} = c.#{TIME_COLUMN}
+              FROM #{calls} AS c
+             WHERE c.id = t.llm_cost_tracker_call_id AND t.id IN (#{list})
+          SQL
+        end
+
+        def behavior_for(entry)
+          entry[:behavior] || LlmCostTracker.configuration.budgets.exceeded_behavior
+        end
+
+        def on_exceeded_for(entry)
+          entry[:on_exceeded] || LlmCostTracker.configuration.budgets.on_exceeded
+        end
+
+        def warn_slow_read(key, window, seconds)
+          return if seconds < SLOW_READ_SECONDS
+
+          @slow_keys ||= Set.new
+          return unless @slow_keys.add?(key)
+
+          Logging.warn(
+            "config.budgets.per_tag[#{key.inspect}] #{window} read took #{(seconds * 1000).round} ms. " \
+            "A tag with few distinct values covers most of the ledger, so its budget check cannot use " \
+            "an index effectively. Budget high-cardinality tags such as a tenant or user id."
+          )
+        end
+
+        def warn_missing_columns
+          return if @missing_columns_warned
+
+          @missing_columns_warned = true
+          Logging.warn(
+            "config.budgets.per_tag is set but llm_cost_tracker_call_tags is missing " \
+            "#{COST_COLUMN} / #{TIME_COLUMN}; per-tag budgets are not enforced. Run the " \
+            "upgrade_per_tag_budgets generator and migrate, or clear config.budgets.per_tag."
+          )
+        end
+      end
+    end
+  end
+end