llm_cost_tracker 0.10.0 → 0.11.0

data/app/controllers/llm_cost_tracker/application_controller.rb

@@ -10,6 +10,7 @@ module LlmCostTracker
 
     before_action :set_dashboard_security_headers
     before_action :ensure_current_schema
+    before_action :assign_dashboard_date_range
 
     helper_method :dashboard_csp_nonce
 
@@ -30,6 +31,12 @@ module LlmCostTracker
       render template: "llm_cost_tracker/shared/setup_required"
     end
 
+    def assign_dashboard_date_range
+      range = LlmCostTracker::Dashboard::DateRange.call(params: params)
+      @from_date = range.from
+      @to_date = range.to
+    end
+
     def render_database_error(error)
       @error = error
       render "llm_cost_tracker/errors/database", status: :internal_server_error
@@ -48,8 +55,13 @@ module LlmCostTracker
       nonce = dashboard_csp_nonce
       response.headers["X-Frame-Options"] = "DENY"
       response.headers["Referrer-Policy"] = "same-origin"
-      response.headers["Content-Security-Policy"] =
-        "default-src 'self'; style-src 'self' 'nonce-#{nonce}'; img-src 'self' data:; frame-ancestors 'none'"
+      response.headers["Content-Security-Policy"] = [
+        "default-src 'self'",
+        "script-src 'self' 'nonce-#{nonce}'",
+        "style-src 'self' 'nonce-#{nonce}'",
+        "img-src 'self' data:",
+        "frame-ancestors 'none'"
+      ].join("; ")
     end
 
     def dashboard_csp_nonce

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -8,18 +8,24 @@ module LlmCostTracker
     CSV_EXPORT_LIMIT = 10_000
     CSV_EXPORT_BATCH_SIZE = 500
     CSV_FORMULA_PREFIXES = ["=", "+", "-", "@", "\t", "\r"].freeze
-    DEFAULT_ORDER = "tracked_at DESC, id DESC"
+    DEFAULT_TIEBREAKER = { tracked_at: :desc, id: :desc }.freeze
+    SORT_OPTIONS = %w[tracked_at provider model input output cost latency].freeze
+    NULLS_LAST_GUARD = {
+      total_cost: Arel.sql("CASE WHEN total_cost IS NULL THEN 1 ELSE 0 END ASC"),
+      latency_ms: Arel.sql("CASE WHEN latency_ms IS NULL THEN 1 ELSE 0 END ASC")
+    }.freeze
 
     def index
       @sort = params[:sort].to_s
+      @dir = params[:dir].to_s
       scope = Dashboard::Filter.call(params: params)
-      scope = scope.unknown_pricing if @sort == "unknown_pricing"
-      ordered_scope = scope.order(Arel.sql(calls_order(@sort)))
+      scope = scope.unknown_pricing if params[:cost_status].to_s == "incomplete"
+      ordered_scope = scope.order(*calls_order(@sort, @dir))
 
       respond_to do |format|
         format.html do
           @page = Dashboard::Pagination.call(params)
-          @calls_count = scope.count
+          @calls_count, @calls_total_cost = scope.pick(Arel.sql("COUNT(*), COALESCE(SUM(total_cost), 0)"))
           @calls = ordered_scope.includes(:tag_records).limit(@page.limit).offset(@page.offset).to_a
         end
         format.csv do
@@ -37,18 +43,19 @@ module LlmCostTracker
 
     private
 
-    def calls_order(sort)
-      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"
-        "CASE WHEN latency_ms IS NULL THEN 1 ELSE 0 END ASC, latency_ms DESC, #{DEFAULT_ORDER}"
-      else
-        DEFAULT_ORDER
+    def calls_order(sort, dir)
+      column = SORT_OPTIONS.include?(sort) ? sort.to_sym : :tracked_at
+      natural = %i[provider model].include?(column) ? :asc : :desc
+      direction = Dashboard::Sort::DIRECTIONS.include?(dir.downcase) ? dir.downcase.to_sym : natural
+
+      case column
+      when :tracked_at then [{ tracked_at: direction, id: direction }]
+      when :provider   then [{ provider: direction, model: :asc, **DEFAULT_TIEBREAKER }]
+      when :model      then [{ model: direction, **DEFAULT_TIEBREAKER }]
+      when :input      then [{ input_tokens: direction, **DEFAULT_TIEBREAKER }]
+      when :output     then [{ output_tokens: direction, **DEFAULT_TIEBREAKER }]
+      when :cost       then [NULLS_LAST_GUARD[:total_cost], { total_cost: direction, **DEFAULT_TIEBREAKER }]
+      when :latency    then [NULLS_LAST_GUARD[:latency_ms], { latency_ms: direction, **DEFAULT_TIEBREAKER }]
       end
     end
 

data/app/controllers/llm_cost_tracker/dashboard_controller.rb

@@ -3,9 +3,6 @@
 module LlmCostTracker
   class DashboardController < ApplicationController
     def index
-      range = Dashboard::DateRange.call(params: params)
-      @from_date = range.from
-      @to_date = range.to
       prev_from, prev_to = previous_range
       filter_params = LlmCostTracker::Dashboard::Params.to_hash(params)
       scope = Dashboard::Filter.call(

data/app/controllers/llm_cost_tracker/models_controller.rb

@@ -4,10 +4,12 @@ module LlmCostTracker
   class ModelsController < ApplicationController
     def index
       @sort = params[:sort].to_s
+      @dir = params[:dir].to_s
       @rows = Dashboard::TopModels.call(
         scope: Dashboard::Filter.call(params: params),
         limit: nil,
-        sort: @sort
+        sort: @sort,
+        direction: @dir
       )
     end
   end

data/app/controllers/llm_cost_tracker/pricing_controller.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  class PricingController < ApplicationController
+    def index
+      @overview = Dashboard::PricingOverview.call
+      requested = params[:source].to_s.to_sym
+      @active_source = @overview.fetch(:sources).key?(requested) ? requested : @overview.fetch(:effective_source)
+      @source_data = @overview.fetch(:sources).fetch(@active_source)
+      @provider_filter = params[:provider].to_s.presence
+      @rows = @source_data.fetch(:rows)
+      @rows = @rows.select { |row| row.provider == @provider_filter } if @provider_filter
+      @providers = @source_data.fetch(:rows).map(&:provider).compact.uniq.sort
+    end
+  end
+end

data/app/controllers/llm_cost_tracker/reconciliation_controller.rb

@@ -30,22 +30,18 @@ module LlmCostTracker
       return redirect_to reconciliation_path, alert: "No importer configured for #{source}" if importer.nil?
 
       result = importer.call
-      if result.respond_to?(:errors) && result.errors.any?
+      if result.errors.any?
         LlmCostTracker::Logging.warn(
           "Reconciliation import for #{source} returned #{result.errors.size} row error(s)"
         )
         return redirect_to(
           reconciliation_path,
-          alert: "Imported #{result.respond_to?(:total_imported) ? result.total_imported : 0} " \
-                 "#{source} rows with #{result.errors.size} row error(s); see Rails logs for details."
+          alert: "Imported #{result.total_imported} #{source} rows " \
+                 "with #{result.errors.size} row error(s); see Rails logs for details."
         )
       end
-      message = if result.respond_to?(:total_imported)
-                  "Imported #{result.total_imported} #{source} rows"
-                else
-                  "Triggered #{source} importer"
-                end
-      redirect_to reconciliation_path, notice: message
+      redirect_to reconciliation_path,
+                  notice: "Imported #{result.total_imported} #{source} rows"
     rescue StandardError => e
       LlmCostTracker::Logging.warn("Reconciliation import failed for #{source}: #{e.class}: #{e.message}")
       redirect_to reconciliation_path,
@@ -59,13 +55,7 @@ module LlmCostTracker
     end
 
     def invoice_scopes
-      connection = LlmCostTracker::ProviderInvoice.connection
-      provider_expr =
-        if LlmCostTracker::Ledger::Schema::Adapter.postgresql?(connection)
-          Arel.sql("metadata->>'provider'")
-        else
-          Arel.sql("JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.provider'))")
-        end
+      provider_expr = Arel.sql(metadata_provider_sql)
       LlmCostTracker::ProviderInvoice
         .group(:source, provider_expr, :currency)
         .order(:source, :currency)
@@ -92,14 +82,18 @@ module LlmCostTracker
     def scope_invoices(scope)
       relation = LlmCostTracker::ProviderInvoice
                  .where(source: scope[:source], currency: scope[:currency])
-      connection = LlmCostTracker::ProviderInvoice.connection
       provider = scope[:provider]
       return relation if provider.nil? || provider.empty?
 
+      relation.where("#{metadata_provider_sql} = ?", provider)
+    end
+
+    def metadata_provider_sql
+      connection = LlmCostTracker::ProviderInvoice.connection
       if LlmCostTracker::Ledger::Schema::Adapter.postgresql?(connection)
-        relation.where("metadata->>'provider' = ?", provider)
+        "metadata->>'provider'"
       else
-        relation.where("JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.provider')) = ?", provider)
+        "JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.provider'))"
       end
     end
   end

data/app/controllers/llm_cost_tracker/tags_controller.rb

@@ -11,7 +11,9 @@ module LlmCostTracker
       @value = params[:tag_value].to_s
 
       if @value.empty?
-        @breakdown = Dashboard::TagBreakdown.call(scope: scope, key: params[:key])
+        @sort = params[:sort].to_s
+        @dir = params[:dir].to_s
+        @breakdown = Dashboard::TagBreakdown.call(scope: scope, key: params[:key], sort: @sort, direction: @dir)
       else
         @key = LlmCostTracker::Tags::Key.validate!(
           params[:key],

data/app/helpers/llm_cost_tracker/application_helper.rb

@@ -15,6 +15,18 @@ module LlmCostTracker
     include TokenUsageHelper
     include InlineStyleHelper
 
+    def dashboard_section
+      path = request.path.to_s
+      return :models if path.start_with?(models_path)
+      return :calls if path.start_with?(calls_path)
+      return :tags if path.start_with?(tags_path)
+      return :data_quality if path.start_with?(data_quality_path)
+      return :pricing if path.start_with?(pricing_path)
+      return :reconciliation if LlmCostTracker.reconciliation_enabled? && path.start_with?(reconciliation_path)
+
+      :overview
+    end
+
     def coverage_percent(numerator, denominator)
       denominator = denominator.to_f
       return 0.0 unless denominator.positive?
@@ -46,14 +58,14 @@ module LlmCostTracker
     end
 
     def pricing_status(call)
-      return "Unknown pricing" if call.total_cost.nil?
+      return "Unknown" if call.total_cost.nil?
       return "Estimated" unless call.has_attribute?(:cost_status)
 
       {
         LlmCostTracker::Billing::CostStatus::COMPLETE => "Estimated",
         LlmCostTracker::Billing::CostStatus::FREE => "Free",
-        LlmCostTracker::Billing::CostStatus::PARTIAL => "Partial pricing"
-      }.fetch(call.cost_status, "Unknown pricing")
+        LlmCostTracker::Billing::CostStatus::PARTIAL => "Partial"
+      }.fetch(call.cost_status, "Unknown")
     end
 
     def percent(value)

data/app/helpers/llm_cost_tracker/chart_helper.rb

@@ -6,7 +6,7 @@ module LlmCostTracker
       return nil if points.blank?
 
       cfg = chart_config(points, comparison_points, height, y_ticks)
-      parts = [chart_svg_open(cfg)]
+      parts = [chart_svg_open(cfg), "<title>Daily spend trend</title>", chart_area_gradient_def]
       parts.concat(chart_grid_and_axis(cfg))
       parts << chart_paths(cfg)
       parts.concat(chart_dots(cfg))
@@ -22,7 +22,7 @@ module LlmCostTracker
     end
 
     def chart_config(points, comparison_points, height, y_ticks)
-      width = 720
+      width = 1180
       pad = { top: 16, right: 16, bottom: 28, left: 56 }
       plot_w = width - pad[:left] - pad[:right]
       plot_h = height - pad[:top] - pad[:bottom]
@@ -31,9 +31,11 @@ module LlmCostTracker
       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?
 
+      peak_index = points.each_with_index.max_by { |point, _| point[:cost].to_f }&.last
       { 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 }
+        comparison_points: comparison_points, comparison_coords: comparison_coords,
+        peak_index: peak_index }
     end
 
     def chart_coords(points, pad, plot_w, plot_h, max_cost)
@@ -51,7 +53,7 @@ module LlmCostTracker
       attrs = [
         %(class="lct-chart"),
         %(viewBox="0 0 #{cfg[:width]} #{cfg[:height]}"),
-        %(preserveAspectRatio="none"),
+        %(preserveAspectRatio="xMidYMid meet"),
         %(role="img"),
         %(aria-label="Daily spend trend")
       ].join(" ")
@@ -114,10 +116,20 @@ module LlmCostTracker
     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"/>)
+      peak = idx == cfg[:peak_index]
+      klass = peak ? "lct-chart-peak" : "lct-chart-dot"
+      radius = peak ? 4 : 3
+      circle = %(<circle class="#{klass}" cx="#{chart_fmt(pt_x)}" cy="#{chart_fmt(pt_y)}" r="#{radius}"/>)
       "<g>#{circle}<title>#{title}</title></g>"
     end
 
+    def chart_area_gradient_def
+      "<defs><linearGradient id=\"lct-chart-grad\" x1=\"0\" x2=\"0\" y1=\"0\" y2=\"1\">" \
+        "<stop offset=\"0%\" stop-color=\"var(--lct-accent)\" stop-opacity=\"0.28\"/>" \
+        "<stop offset=\"100%\" stop-color=\"var(--lct-accent)\" stop-opacity=\"0.02\"/>" \
+        "</linearGradient></defs>"
+    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)
@@ -127,7 +139,11 @@ module LlmCostTracker
     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>)
+      anchor = if idx.zero? then "start"
+               elsif idx == cfg[:n] - 1 then "end"
+               else "middle"
+               end
+      %(<text class="lct-chart-axis" x="#{chart_fmt(pt_x)}" y="#{label_y}" text-anchor="#{anchor}">#{label}</text>)
     end
   end
 end

data/app/helpers/llm_cost_tracker/sortable_table_helper.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module SortableTableHelper
+    def sortable_header(label, column, num: false)
+      state = sortable_state(column, num: num)
+      classes = ["lct-sortable"]
+      classes << "lct-num" if num
+      classes << "lct-sorted" if state[:active]
+
+      href = dashboard_filter_path(current_query(sort: column, dir: state[:next_dir], page: nil))
+      tag.th(class: classes.join(" "), "aria-sort": state[:aria_sort]) do
+        link_to(href) { safe_join([label, " ", tag.span(state[:arrow], class: "lct-sort-ind")]) }
+      end
+    end
+
+    private
+
+    def sortable_state(column, num:)
+      current_sort = params[:sort].to_s
+      current_dir = Dashboard::Sort::DIRECTIONS.include?(params[:dir].to_s) ? params[:dir].to_s : nil
+      natural_dir = num ? "desc" : "asc"
+      active = current_sort == column
+      effective_dir = active ? (current_dir || natural_dir) : natural_dir
+      flipped = effective_dir == "asc" ? "desc" : "asc"
+
+      {
+        active: active,
+        next_dir: active ? flipped : natural_dir,
+        arrow: active && effective_dir == "asc" ? "▲" : "▼",
+        aria_sort: sortable_aria(active, effective_dir)
+      }
+    end
+
+    def sortable_aria(active, effective_dir)
+      return "none" unless active
+
+      effective_dir == "asc" ? "ascending" : "descending"
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Dashboard
+    class PricingOverview
+      SOURCES = %i[overrides file bundled].freeze
+      RATE_COLUMNS = %i[input output cache_read_input cache_write_input batch_input batch_output].freeze
+      Row = Data.define(:provider, :model, :rates)
+
+      class << self
+        def call
+          new.call
+        end
+      end
+
+      def call
+        sources = SOURCES.each_with_object({}) do |source, acc|
+          built = build_source(source)
+          acc[source] = built if built
+        end
+        {
+          sources: sources,
+          effective_source: sources.keys.first || :bundled
+        }
+      end
+
+      private
+
+      def build_source(source)
+        case source
+        when :overrides then build_overrides
+        when :file then build_file
+        when :bundled then build_bundled
+        end
+      end
+
+      def build_overrides
+        prices = LlmCostTracker.configuration.pricing_overrides
+        return nil if prices.nil? || prices.empty?
+
+        {
+          label: "Overrides",
+          subtitle: "config.pricing_overrides",
+          updated_at: nil,
+          currency: nil,
+          rows: build_rows(prices)
+        }
+      end
+
+      def build_file
+        path = LlmCostTracker.configuration.prices_file
+        return nil unless path && File.exist?(path)
+
+        prices = Pricing::Registry.file_prices(path)
+        return nil if prices.empty?
+
+        meta = Pricing::Registry.file_metadata(path)
+        {
+          label: "Custom file",
+          subtitle: path.to_s,
+          updated_at: meta["updated_at"] || Pricing::Lookup.prices_file_mtime_iso,
+          currency: meta["currency"] || Pricing::Lookup::DEFAULT_CURRENCY,
+          rows: build_rows(prices)
+        }
+      end
+
+      def build_bundled
+        prices = Pricing::Registry.builtin_prices
+        meta = Pricing::Registry.metadata
+        {
+          label: "Bundled",
+          subtitle: "ships with the gem",
+          updated_at: meta["updated_at"],
+          currency: meta["currency"] || Pricing::Lookup::DEFAULT_CURRENCY,
+          rows: build_rows(prices)
+        }
+      end
+
+      def build_rows(prices)
+        rows = prices.map do |key, rates|
+          provider, model = split_key(key.to_s)
+          Row.new(provider: provider, model: model, rates: rates)
+        end
+        rows.sort_by { |row| [row.provider || "~", row.model] }
+      end
+
+      def split_key(key)
+        provider, model = key.split("/", 2)
+        return [provider, model] if model
+
+        [nil, provider]
+      end
+    end
+  end
+end

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

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-require "llm_cost_tracker/ledger/schema/calls"
-require "llm_cost_tracker/ledger/schema/call_line_items"
-require "llm_cost_tracker/ledger/schema/call_tags"
-require "llm_cost_tracker/ledger/schema/call_rollups"
+require "llm_cost_tracker/ledger"
 
 module LlmCostTracker
   module Dashboard
@@ -12,34 +9,18 @@ module LlmCostTracker
       DOCS_HINT = "See docs/upgrading.md for the migration path."
       MUTEX = Mutex.new
 
-      CORE_SCHEMA_CHECKS = [
-        [
-          LlmCostTracker::Ledger::Schema::Calls,
-          "The llm_cost_tracker_calls table does not match the current LLM Cost Tracker schema."
-        ],
-        [
-          LlmCostTracker::Ledger::Schema::CallLineItems,
-          "The llm_cost_tracker_call_line_items table does not match the current LLM Cost Tracker schema."
-        ],
-        [
-          LlmCostTracker::Ledger::Schema::CallTags,
-          "The llm_cost_tracker_call_tags table does not match the current LLM Cost Tracker schema."
-        ]
-      ].freeze
-
-      OPTIONAL_CALL_ROLLUPS_CHECK = [
-        LlmCostTracker::Ledger::Schema::CallRollups,
-        "The llm_cost_tracker_call_rollups table does not match the current LLM Cost Tracker schema."
-      ].freeze
-
-      private_constant :MUTEX, :CORE_SCHEMA_CHECKS, :OPTIONAL_CALL_ROLLUPS_CHECK, :DOCS_HINT
+      private_constant :MUTEX, :DOCS_HINT
 
       class << self
         def current
-          return @cached if defined?(@cached)
+          fingerprint = schema_fingerprint
 
           MUTEX.synchronize do
-            @cached = compute unless defined?(@cached)
+            if !defined?(@cache_fingerprint) || @cache_fingerprint != fingerprint
+              LlmCostTracker::Call.reset_column_information
+              @cached = compute
+              @cache_fingerprint = fingerprint
+            end
           end
           @cached
         end
@@ -47,11 +28,23 @@ module LlmCostTracker
         def reset!
           MUTEX.synchronize do
             remove_instance_variable(:@cached) if defined?(@cached)
+            remove_instance_variable(:@cache_fingerprint) if defined?(@cache_fingerprint)
           end
         end
 
         private
 
+        SCHEMA_MIGRATIONS_TABLE = "schema_migrations"
+        private_constant :SCHEMA_MIGRATIONS_TABLE
+
+        def schema_fingerprint
+          connection = ActiveRecord::Base.connection
+          quoted = connection.quote_table_name(SCHEMA_MIGRATIONS_TABLE)
+          connection.query_value("SELECT MAX(version) FROM #{quoted}")
+        rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
+          nil
+        end
+
         def compute
           LlmCostTracker::Logging.debug("Dashboard::SetupState recomputing")
           return calls_table_missing unless LlmCostTracker::Call.table_exists?
@@ -64,17 +57,18 @@ module LlmCostTracker
         end
 
         def schema_checks_for_current_config
-          return CORE_SCHEMA_CHECKS unless LlmCostTracker.configuration.cache_rollups
+          return LlmCostTracker::Ledger::Schema::CORE_SCHEMAS unless LlmCostTracker.configuration.cache_rollups
 
-          CORE_SCHEMA_CHECKS + [OPTIONAL_CALL_ROLLUPS_CHECK]
+          LlmCostTracker::Ledger::Schema::CORE_SCHEMAS + [LlmCostTracker::Ledger::Schema::CACHE_ROLLUPS_SCHEMA]
         end
 
         def drift_in(checks)
-          checks.each do |schema, message|
+          checks.each do |schema, table|
             errors = schema.current_schema_errors
             next if errors.empty?
 
-            return SetupRequired.new(message: message, details: errors + [DOCS_HINT])
+            message = "The #{table} table does not match the current LLM Cost Tracker schema."
+            return SetupRequired.new(message: message, details: errors)
           end
           nil
         end
@@ -85,7 +79,7 @@ module LlmCostTracker
             unless connection.data_source_exists?(table)
               return SetupRequired.new(
                 message: "The #{table} table is required when reconciliation is enabled.",
-                details: ["run bin/rails generate llm_cost_tracker:reconciliation && bin/rails db:migrate", DOCS_HINT]
+                details: ["bin/rails generate llm_cost_tracker:reconciliation && bin/rails db:migrate"]
               )
             end
 
@@ -93,7 +87,7 @@ module LlmCostTracker
             next if errors.empty?
 
             message = "The #{table} table does not match the current LLM Cost Tracker schema."
-            return SetupRequired.new(message: message, details: errors + [DOCS_HINT])
+            return SetupRequired.new(message: message, details: errors)
           end
           nil
         end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Dashboard
+    module Sort
+      DIRECTIONS = %w[asc desc].freeze
+    end
+  end
+end

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

@@ -4,21 +4,25 @@ module LlmCostTracker
   module Dashboard
     class TagBreakdown
       DEFAULT_LIMIT = 100
+      SORT_OPTIONS = %w[value calls cost avg_cost].freeze
+      DEFAULT_DIRECTIONS = { "value" => "asc", "calls" => "desc", "cost" => "desc", "avg_cost" => "desc" }.freeze
       Row = Data.define(:value, :calls, :total_cost, :average_cost_per_call, :share_percent)
 
       class << self
-        def call(key:, scope: LlmCostTracker::Call.all, limit: DEFAULT_LIMIT)
-          new(scope: scope, key: key, limit: limit)
+        def call(key:, scope: LlmCostTracker::Call.all, limit: DEFAULT_LIMIT, sort: "cost", direction: nil)
+          new(scope: scope, key: key, limit: limit, sort: sort, direction: direction)
         end
       end
 
       attr_reader :limit
 
-      def initialize(scope:, key:, limit:)
+      def initialize(scope:, key:, limit:, sort: "cost", direction: nil)
         @scope = scope
         @key = LlmCostTracker::Tags::Key.validate!(key, error_class: LlmCostTracker::InvalidFilterError)
         limit = limit.to_i
         @limit = limit.positive? ? [limit, DEFAULT_LIMIT].min : DEFAULT_LIMIT
+        @sort = SORT_OPTIONS.include?(sort.to_s) ? sort.to_s : "cost"
+        @direction = Sort::DIRECTIONS.include?(direction.to_s) ? direction.to_s : DEFAULT_DIRECTIONS[@sort]
       end
 
       def rows
@@ -51,7 +55,7 @@ module LlmCostTracker
 
       private
 
-      attr_reader :scope, :key
+      attr_reader :scope, :key, :sort, :direction
 
       def summary_counts
         @summary_counts ||= scope.klass.find_by_sql(summary_sql).first
@@ -67,11 +71,21 @@ module LlmCostTracker
           INNER JOIN #{call_tag_table} t ON t.llm_cost_tracker_call_id = sub.id AND t.#{quote_column('key')} = #{quoted_key}
           WHERE #{tag_present_predicate}
           GROUP BY #{tag_value_column}
-          ORDER BY total_cost DESC, calls DESC, value ASC
+          ORDER BY #{order_clause}
           LIMIT #{limit}
         SQL
       end
 
+      def order_clause
+        dir = direction.upcase
+        case sort
+        when "value"    then "#{tag_value_column} #{dir}"
+        when "calls"    then "COUNT(*) #{dir}, total_cost DESC"
+        when "avg_cost" then "average_cost_per_call #{dir}, total_cost DESC"
+        else "total_cost #{dir}, calls DESC, value ASC"
+        end
+      end
+
       def summary_sql
         <<~SQL.squish
           SELECT COUNT(*) AS total_calls,