llm_cost_tracker 0.2.0.alpha2 → 0.3.0

data/app/controllers/llm_cost_tracker/application_controller.rb

@@ -14,17 +14,11 @@ module LlmCostTracker
     private
 
     def ensure_llm_api_calls_table
-      return if llm_api_calls_table_available?
+      return if LlmCostTracker::LlmApiCall.table_exists?
 
       render template: "llm_cost_tracker/shared/setup_required"
     end
 
-    def llm_api_calls_table_available?
-      LlmCostTracker::LlmApiCall.table_exists?
-    rescue ActiveRecord::ConnectionNotEstablished, ActiveRecord::StatementInvalid
-      false
-    end
-
     def render_database_error(error)
       @error = error
       render "llm_cost_tracker/errors/database", status: :internal_server_error

data/app/controllers/llm_cost_tracker/assets_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  class AssetsController < ActionController::Base
+    skip_forgery_protection if respond_to?(:skip_forgery_protection)
+
+    def stylesheet
+      response.set_header("Cache-Control", "public, max-age=31536000, immutable")
+      send_file LlmCostTracker::Assets::STYLESHEET_PATH, type: "text/css", disposition: "inline"
+    end
+  end
+end

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -4,15 +4,8 @@ require "csv"
 
 module LlmCostTracker
   class CallsController < ApplicationController
-    SORT_ORDERS = {
-      "expensive"       => "total_cost DESC NULLS LAST, tracked_at DESC",
-      "input"           => "input_tokens DESC, tracked_at DESC",
-      "output"          => "output_tokens DESC, tracked_at DESC",
-      "slow"            => "latency_ms DESC NULLS LAST, tracked_at DESC",
-      "unknown_pricing" => "tracked_at DESC, id DESC"
-    }.freeze
-
     CSV_EXPORT_LIMIT = 10_000
+    CSV_FORMULA_PREFIXES = ["=", "+", "-", "@", "\t", "\r"].freeze
 
     def index
       @sort = params[:sort].to_s
@@ -46,7 +39,24 @@ module LlmCostTracker
     private
 
     def calls_order(sort)
-      SORT_ORDERS[sort] || "tracked_at DESC, id DESC"
+      case sort
+      when "expensive"
+        "CASE WHEN total_cost IS NULL THEN 1 ELSE 0 END ASC, total_cost DESC, #{default_order}"
+      when "input"
+        "input_tokens DESC, #{default_order}"
+      when "output"
+        "output_tokens DESC, #{default_order}"
+      when "slow"
+        return default_order unless LlmApiCall.latency_column?
+
+        "CASE WHEN latency_ms IS NULL THEN 1 ELSE 0 END ASC, latency_ms DESC, #{default_order}"
+      else
+        default_order
+      end
+    end
+
+    def default_order
+      "tracked_at DESC, id DESC"
     end
 
     def render_csv(relation)
@@ -60,18 +70,25 @@ module LlmCostTracker
         relation.each do |call|
           row = [
             call.tracked_at&.utc&.iso8601,
-            call.provider,
-            call.model,
+            csv_safe(call.provider),
+            csv_safe(call.model),
             call.input_tokens,
             call.output_tokens,
             call.total_tokens,
             call.total_cost
           ]
           row << call.latency_ms if latency
-          row << call.parsed_tags.to_json
+          row << csv_safe(call.parsed_tags.to_json)
           csv << row
         end
       end
     end
+
+    def csv_safe(value)
+      return value if value.nil?
+
+      string = value.to_s
+      CSV_FORMULA_PREFIXES.include?(string[0]) ? "'#{string}" : string
+    end
   end
 end

data/app/controllers/llm_cost_tracker/dashboard_controller.rb

@@ -4,12 +4,16 @@ module LlmCostTracker
   class DashboardController < ApplicationController
     def index
       @from_date, @to_date = overview_range
+      prev_from, prev_to = previous_range
       scope = Dashboard::Filter.call(params: overview_filter_params)
       previous_scope = Dashboard::Filter.call(params: previous_filter_params)
+      model_rows = Dashboard::TopModels.call(scope: scope, limit: 10)
 
       @stats = Dashboard::OverviewStats.call(scope: scope, previous_scope: previous_scope)
       @time_series = Dashboard::TimeSeries.call(scope: scope, from: @from_date, to: @to_date)
-      @top_models = Dashboard::TopModels.call(scope: scope, limit: 5)
+      @comparison_series = Dashboard::TimeSeries.call(scope: previous_scope, from: prev_from, to: prev_to)
+      @spend_anomaly = Dashboard::SpendAnomaly.call(from: @from_date, to: @to_date, scope: scope)
+      @top_models = model_rows.first(5)
       @providers = Dashboard::ProviderBreakdown.call(scope: scope)
     end
 

data/app/helpers/llm_cost_tracker/application_helper.rb

@@ -4,6 +4,12 @@ require "json"
 
 module LlmCostTracker
   module ApplicationHelper
+    include DashboardFilterHelper
+    include DashboardFilterOptionsHelper
+    include DashboardQueryHelper
+    include ChartHelper
+    include PaginationHelper
+
     def coverage_percent(numerator, denominator)
       return 0.0 unless denominator.to_i.positive?
 
@@ -46,19 +52,19 @@ module LlmCostTracker
     end
 
     def delta_badge(delta_percent, mode: :cost)
-      return { text: "vs. prior: n/a", css_class: "lct-delta lct-delta-neutral" } if delta_percent.nil?
+      return { text: "n/a vs. prior", css_class: "lct-delta-badge lct-delta-neutral" } if delta_percent.nil?
 
       rounded = delta_percent.round(1)
-      return { text: "= vs. prior", css_class: "lct-delta lct-delta-neutral" } if rounded.zero?
+      return { text: "0.0% vs. prior", css_class: "lct-delta-badge lct-delta-neutral" } if rounded.zero?
 
       sign = rounded.positive? ? "+" : ""
       text = "#{sign}#{format('%.1f', rounded)}% vs. prior"
       css_class = if mode == :neutral
-                    "lct-delta lct-delta-neutral"
+                    "lct-delta-badge lct-delta-neutral"
                   elsif rounded.positive?
-                    "lct-delta lct-delta-up"
+                    "lct-delta-badge lct-delta-up"
                   else
-                    "lct-delta lct-delta-down"
+                    "lct-delta-badge lct-delta-down"
                   end
 
       { text: text, css_class: css_class }
@@ -71,6 +77,18 @@ module LlmCostTracker
       "#{[(value.to_f / max) * 100.0, 100.0].min.round(2)}%"
     end
 
+    def stack_segments(entries)
+      total = entries.sum { |entry| entry[:value].to_f }
+      return [] unless total.positive?
+
+      entries.filter_map do |entry|
+        value = entry[:value].to_f
+        next unless value.positive?
+
+        entry.merge(percent: (value / total) * 100.0)
+      end
+    end
+
     def safe_json(value)
       parsed = value.is_a?(String) ? JSON.parse(value) : value
       JSON.pretty_generate(parsed || {})
@@ -87,10 +105,33 @@ module LlmCostTracker
       summary.join(", ")
     end
 
+    def tag_chip_entries(tags, limit: 3)
+      normalized = normalized_tags(tags)
+      return [] if normalized.empty?
+
+      visible = normalized.first(limit).map do |key, value|
+        { key: key.to_s, value: tag_value_summary(value) }
+      end
+      visible << { more: normalized.size - limit } if normalized.size > limit
+      visible
+    end
+
+    def budget_fill_modifier(percent)
+      percent = percent.to_f
+      return "lct-budget-fill--over" if percent >= 100.0
+      return "lct-budget-fill--warn" if percent >= 80.0
+
+      ""
+    end
+
     def current_query(overrides = {})
       request.query_parameters.symbolize_keys.merge(overrides)
     end
 
+    def calls_query_for_model(provider:, model:)
+      current_query(provider: provider, model: model, page: nil, per: nil, format: nil)
+    end
+
     private
 
     def normalized_tags(tags)

data/app/helpers/llm_cost_tracker/chart_helper.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module ChartHelper
+    def spend_chart_svg(points, comparison_points: nil, height: 180, y_ticks: 3)
+      return nil if points.blank?
+
+      cfg = chart_config(points, comparison_points, height, y_ticks)
+      parts = [chart_svg_open(cfg)]
+      parts.concat(chart_grid_and_axis(cfg))
+      parts << chart_paths(cfg)
+      parts.concat(chart_dots(cfg))
+      parts.concat(chart_x_labels(cfg))
+      parts << "</svg>"
+      parts.join.html_safe
+    end
+
+    private
+
+    def chart_fmt(value)
+      format("%.2f", value)
+    end
+
+    def chart_config(points, comparison_points, height, y_ticks)
+      width = 720
+      pad = { top: 16, right: 16, bottom: 28, left: 56 }
+      plot_w = width - pad[:left] - pad[:right]
+      plot_h = height - pad[:top] - pad[:bottom]
+      all_costs = points.map { |p| p[:cost].to_f } + Array(comparison_points).map { |p| p[:cost].to_f }
+      max_cost = [all_costs.max.to_f, 0.0001].max
+      coords = chart_coords(points, pad, plot_w, plot_h, max_cost)
+      comparison_coords = chart_coords(comparison_points, pad, plot_w, plot_h, max_cost) if comparison_points.present?
+
+      { width: width, height: height, pad: pad, plot_w: plot_w, plot_h: plot_h,
+        max_cost: max_cost, n: points.size, y_ticks: y_ticks, points: points, coords: coords,
+        comparison_points: comparison_points, comparison_coords: comparison_coords }
+    end
+
+    def chart_coords(points, pad, plot_w, plot_h, max_cost)
+      n = points.size
+      step = n > 1 ? plot_w.to_f / (n - 1) : 0.0
+
+      points.each_with_index.map do |point, idx|
+        x = pad[:left] + (idx * step)
+        y = pad[:top] + plot_h - ((point[:cost].to_f / max_cost) * plot_h)
+        [x, y]
+      end
+    end
+
+    def chart_svg_open(cfg)
+      attrs = [
+        %(class="lct-chart"),
+        %(viewBox="0 0 #{cfg[:width]} #{cfg[:height]}"),
+        %(preserveAspectRatio="none"),
+        %(role="img"),
+        %(aria-label="Daily spend trend")
+      ].join(" ")
+      "<svg #{attrs}>"
+    end
+
+    def chart_grid_and_axis(cfg)
+      (0..cfg[:y_ticks]).map { |i| chart_tick_line(cfg, i) }
+    end
+
+    def chart_tick_line(cfg, idx)
+      pad = cfg[:pad]
+      right_x = chart_fmt(pad[:left] + cfg[:plot_w])
+      left_x = chart_fmt(pad[:left])
+      text_x = chart_fmt(pad[:left] - 8)
+      value = cfg[:max_cost] * (cfg[:y_ticks] - idx).to_f / cfg[:y_ticks]
+      y = chart_fmt(pad[:top] + (cfg[:plot_h] * idx.to_f / cfg[:y_ticks]))
+      label_y = chart_fmt(pad[:top] + (cfg[:plot_h] * idx.to_f / cfg[:y_ticks]) + 3)
+      grid = %(<line class="lct-chart-grid" x1="#{left_x}" x2="#{right_x}" y1="#{y}" y2="#{y}"/>)
+      label = format("%.2f", value)
+      text = %(<text class="lct-chart-axis" x="#{text_x}" y="#{label_y}" text-anchor="end">$#{label}</text>)
+      "#{grid}#{text}"
+    end
+
+    def chart_paths(cfg)
+      line = build_line_path(cfg[:coords])
+      base_y = cfg[:pad][:top] + cfg[:plot_h]
+      area = build_area_path(cfg[:coords], cfg, base_y, line)
+      secondary = if cfg[:comparison_coords].present?
+                    %(<path class="lct-chart-line-secondary" d="#{build_line_path(cfg[:comparison_coords])}"/>)
+                  else
+                    ""
+                  end
+      %(<path class="lct-chart-area" d="#{area}"/>#{secondary}<path class="lct-chart-line" d="#{line}"/>)
+    end
+
+    def build_line_path(coords)
+      coords.each_with_index.map do |(x, y), idx|
+        "#{idx.zero? ? 'M' : 'L'}#{chart_fmt(x)},#{chart_fmt(y)}"
+      end.join(" ")
+    end
+
+    def build_area_path(coords, cfg, base_y, line)
+      if coords.size == 1
+        x, y = coords.first
+        left = chart_fmt(cfg[:pad][:left])
+        right = chart_fmt(cfg[:pad][:left] + cfg[:plot_w])
+        "M#{left},#{chart_fmt(base_y)} L#{chart_fmt(x)},#{chart_fmt(y)} L#{right},#{chart_fmt(base_y)} Z"
+      else
+        first_x = chart_fmt(coords.first[0])
+        last_x = chart_fmt(coords.last[0])
+        "#{line} L#{last_x},#{chart_fmt(base_y)} L#{first_x},#{chart_fmt(base_y)} Z"
+      end
+    end
+
+    def chart_dots(cfg)
+      cfg[:coords].each_with_index.map { |(pt_x, pt_y), idx| chart_dot(cfg, pt_x, pt_y, idx) }
+    end
+
+    def chart_dot(cfg, pt_x, pt_y, idx)
+      point = cfg[:points][idx]
+      title = ERB::Util.html_escape("#{point[:label]}: #{money(point[:cost])}")
+      circle = %(<circle class="lct-chart-dot" cx="#{chart_fmt(pt_x)}" cy="#{chart_fmt(pt_y)}" r="3"/>)
+      "<g>#{circle}<title>#{title}</title></g>"
+    end
+
+    def chart_x_labels(cfg)
+      indexes = cfg[:n] <= 2 ? (0...cfg[:n]).to_a : [0, cfg[:n] / 2, cfg[:n] - 1].uniq
+      label_y = chart_fmt(cfg[:height] - 8)
+      indexes.map { |idx| chart_x_label(cfg, idx, label_y) }
+    end
+
+    def chart_x_label(cfg, idx, label_y)
+      pt_x, = cfg[:coords][idx]
+      label = ERB::Util.html_escape(cfg[:points][idx][:label])
+      %(<text class="lct-chart-axis" x="#{chart_fmt(pt_x)}" y="#{label_y}" text-anchor="middle">#{label}</text>)
+    end
+  end
+end

data/app/helpers/llm_cost_tracker/dashboard_filter_helper.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module DashboardFilterHelper
+    FILTER_PARAM_KEYS = %i[from to provider model stream usage_source tag sort page per].freeze
+
+    STREAM_FILTER_OPTIONS = [
+      ["Streaming only", "yes"],
+      ["Non-streaming only", "no"]
+    ].freeze
+
+    def any_filter_applied?
+      FILTER_PARAM_KEYS.any? { |key| params[key].present? }
+    end
+
+    def active_tag_filters
+      tag_params = normalized_query_tags(params[:tag])
+      return [] unless tag_params.is_a?(Hash)
+
+      tag_params.filter_map do |key, value|
+        next if key.blank? || value.blank?
+
+        {
+          label: "Tag",
+          value: "#{key}=#{value}",
+          path: dashboard_filter_path(current_query(tag: tag_params.except(key.to_s).presence, page: nil))
+        }
+      end
+    end
+
+    def dashboard_date_range_label(from, to)
+      from_label = short_date_label(from) || "Any time"
+      to_label = short_date_label(to) || "Now"
+      "#{from_label} - #{to_label}"
+    end
+
+    private
+
+    def short_date_label(value)
+      return nil if value.blank?
+
+      Date.iso8601(value.to_s).strftime("%b %-d, %Y")
+    rescue ArgumentError
+      value.to_s
+    end
+  end
+end

data/app/helpers/llm_cost_tracker/dashboard_filter_options_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module DashboardFilterOptionsHelper
+    def provider_filter_options(filter_params: params)
+      filter_options_for(:provider, filter_params: filter_params)
+    end
+
+    def model_filter_options(filter_params: params)
+      filter_options_for(:model, filter_params: filter_params)
+    end
+
+    private
+
+    def filter_options_for(column, filter_params:)
+      source = filter_source_hash(filter_params)
+      scope_params = source.stringify_keys.merge(
+        column.to_s => nil, "format" => nil, "page" => nil, "per" => nil, "sort" => nil
+      )
+      values = LlmCostTracker::Dashboard::Filter.call(params: scope_params)
+                                                .where.not(column => [nil, ""])
+                                                .distinct.order(column).pluck(column)
+      current = source[column.to_s].presence || source[column].presence
+      values.unshift(current) if current && !values.include?(current)
+      values
+    end
+
+    def filter_source_hash(filter_params)
+      return filter_params.to_unsafe_h if filter_params.respond_to?(:to_unsafe_h)
+
+      filter_params.to_h
+    end
+  end
+end

data/app/helpers/llm_cost_tracker/dashboard_query_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module DashboardQueryHelper
+    def dashboard_filter_path(query)
+      cleaned = clean_dashboard_query(query)
+      return request.path if cleaned.blank?
+
+      "#{request.path}?#{cleaned.to_query}"
+    end
+
+    def calls_query_for_tag(key:, value:)
+      query = current_query(page: nil, per: nil, format: nil)
+      tags = normalized_query_tags(query[:tag])
+      query[:tag] = tags.merge(key.to_s => value.to_s)
+      query
+    end
+
+    private
+
+    def normalized_query_tags(tags)
+      return {} unless tags
+
+      tags = tags.to_unsafe_h if tags.respond_to?(:to_unsafe_h)
+      tags = tags.to_h if tags.respond_to?(:to_h)
+      return {} unless tags.is_a?(Hash)
+
+      tags.transform_keys(&:to_s).transform_values(&:to_s)
+    end
+
+    def clean_dashboard_query(value)
+      return clean_dashboard_hash(value.to_unsafe_h) if value.is_a?(ActionController::Parameters)
+      return clean_dashboard_hash(value) if value.is_a?(Hash)
+      return clean_dashboard_array(value) if value.is_a?(Array)
+      return clean_dashboard_string(value) if value.is_a?(String)
+
+      value
+    end
+
+    def clean_dashboard_hash(hash)
+      hash.each_with_object({}) do |(key, nested), cleaned|
+        nested = clean_dashboard_query(nested)
+        next if nested.nil? || nested == {} || nested == []
+
+        cleaned[key] = nested
+      end
+    end
+
+    def clean_dashboard_array(array)
+      array.filter_map { |item| clean_dashboard_query(item) }.presence
+    end
+
+    def clean_dashboard_string(string)
+      stripped = string.strip
+      stripped.empty? ? nil : stripped
+    end
+  end
+end

data/app/helpers/llm_cost_tracker/pagination_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module PaginationHelper
+    PER_PAGE_CHOICES = [25, 50, 100, 200].freeze
+
+    def pagination_page_items(current, total_pages, window: 1)
+      return (1..total_pages).to_a if total_pages <= (window * 2) + 5
+
+      anchors = [1, total_pages, current, current - window, current + window]
+      pages = anchors.grep(1..total_pages).uniq.sort
+      pages.each_with_index.flat_map do |page, index|
+        gap = index.positive? && page - pages[index - 1] > 1 ? [:gap] : []
+        gap << page
+      end
+    end
+  end
+end

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

@@ -8,15 +8,18 @@ module LlmCostTracker
       :untagged_calls_count,
       :missing_latency_count,
       :latency_column_present,
+      :streaming_count,
+      :streaming_missing_usage_count,
+      :stream_column_present,
       :unknown_pricing_by_model
     )
 
-    # Computes data quality metrics: coverage of cost, tags, and latency.
     class DataQuality
       class << self
         def call(scope: LlmCostTracker::LlmApiCall.all)
           total = scope.count
           latency_present = LlmCostTracker::LlmApiCall.latency_column?
+          stream_present = LlmCostTracker::LlmApiCall.stream_column?
 
           DataQualityStats.new(
             total_calls: total,
@@ -24,6 +27,9 @@ module LlmCostTracker
             untagged_calls_count: total - scope.with_json_tags.count,
             missing_latency_count: latency_present ? scope.where(latency_ms: nil).count : nil,
             latency_column_present: latency_present,
+            streaming_count: stream_present ? scope.streaming.count : nil,
+            streaming_missing_usage_count: streaming_missing_usage_count(scope, stream_present),
+            stream_column_present: stream_present,
             unknown_pricing_by_model: scope.unknown_pricing
                                       .group(:model)
                                       .order(Arel.sql("COUNT(*) DESC"))
@@ -32,6 +38,15 @@ module LlmCostTracker
                                       .to_h
           )
         end
+
+        private
+
+        def streaming_missing_usage_count(scope, stream_present)
+          return nil unless stream_present
+          return nil unless LlmCostTracker::LlmApiCall.usage_source_column?
+
+          scope.streaming_missing_usage.count
+        end
       end
     end
   end

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

@@ -25,6 +25,8 @@ module LlmCostTracker
         filtered_scope = apply_date_filters(filtered_scope)
         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)
         apply_tag_filters(filtered_scope)
       end
 
@@ -64,11 +66,28 @@ module LlmCostTracker
         relation.by_tags(tags)
       end
 
+      def apply_stream_filter(relation)
+        value = string_param(:stream)
+        return relation if value.nil?
+        return relation unless relation.klass.stream_column?
+
+        case value.downcase
+        when "yes", "true", "1" then relation.where(stream: true)
+        when "no", "false", "0" then relation.where(stream: [false, nil])
+        else relation
+        end
+      end
+
+      def apply_usage_source_filter(relation)
+        value = string_param(:usage_source)
+        return relation if value.nil?
+        return relation unless relation.klass.usage_source_column?
+
+        relation.where(usage_source: value)
+      end
+
       def tag_params
         tags = hash_param(:tag)
-        tag_key = string_param(:tag_key)
-        tag_value = string_param(:tag_value)
-        tags = tags.merge(tag_key => tag_value) if tag_key && tag_value
 
         tags.each_with_object({}) do |(key, value), normalized|
           value = normalized_string(value)

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

@@ -74,11 +74,26 @@ module LlmCostTracker
           budget = LlmCostTracker.configuration.monthly_budget
           return nil unless budget
 
+          now = Time.now.utc
+          month_start = now.beginning_of_month
+          month_end = now.end_of_month
           spent = LlmCostTracker::LlmApiCall.this_month.total_cost
+          elapsed_seconds = now - month_start
+          total_seconds = month_end - month_start
+          projected_spent = if spent.zero? || !elapsed_seconds.positive?
+                              spent
+                            else
+                              spent * (total_seconds / elapsed_seconds)
+                            end
+
           {
             budget: budget.to_f,
             spent: spent,
-            percent_used: budget.to_f.positive? ? (spent / budget.to_f) * 100.0 : 0.0
+            percent_used: budget.to_f.positive? ? (spent / budget.to_f) * 100.0 : 0.0,
+            projected_spent: projected_spent,
+            projected_percent_used: budget.to_f.positive? ? (projected_spent / budget.to_f) * 100.0 : 0.0,
+            projected_delta: projected_spent - budget.to_f,
+            projection_end_label: month_end.strftime("%b %-d")
           }
         end
       end