llm_cost_tracker 0.9.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
 
@@ -22,7 +23,7 @@ module LlmCostTracker
     private
 
     def ensure_current_schema
-      drift = LlmCostTracker::DashboardSetupState.current
+      drift = LlmCostTracker::Dashboard::SetupState.current
       return unless drift
 
       @setup_message = drift.message
@@ -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

@@ -6,24 +6,31 @@ require "json"
 module LlmCostTracker
   class CallsController < ApplicationController
     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
           response.headers["Cache-Control"] = "no-store"
-          send_data render_csv(ordered_scope.limit(CSV_EXPORT_LIMIT)),
+          send_data render_csv(ordered_scope),
                     type: "text/csv",
                     disposition: %(attachment; filename="llm_calls_#{Time.now.utc.strftime('%Y%m%d_%H%M%S')}.csv")
         end
@@ -31,23 +38,24 @@ module LlmCostTracker
     end
 
     def show
-      @call = LlmCostTracker::Call.find(params[:id])
+      @call = LlmCostTracker::Call.includes(:line_items, :tag_records).find(params[:id])
     end
 
     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
 
@@ -55,13 +63,24 @@ module LlmCostTracker
       fields = csv_fields
       CSV.generate do |csv|
         csv << fields.map(&:to_s)
-
-        relation.includes(:tag_records).each do |call|
+        each_export_batch(relation) do |call|
           csv << fields.map { |field| csv_value(field, call) }
         end
       end
     end
 
+    def each_export_batch(relation, &)
+      offset = 0
+      while offset < CSV_EXPORT_LIMIT
+        batch_size = [CSV_EXPORT_BATCH_SIZE, CSV_EXPORT_LIMIT - offset].min
+        batch = relation.limit(batch_size).offset(offset).preload(:tag_records).to_a
+        break if batch.empty?
+
+        batch.each(&)
+        offset += batch.size
+      end
+    end
+
     def csv_fields
       %i[tracked_at provider model] +
         TokenUsage.members +

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?
@@ -38,7 +50,7 @@ module LlmCostTracker
     end
 
     def number(value)
-      number_with_delimiter(value.to_i)
+      number_with_delimiter(value)
     end
 
     def format_date(value)
@@ -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/models/llm_cost_tracker/provider_invoice_import.rb

@@ -8,17 +8,22 @@ module LlmCostTracker
     STATES = [STATE_RUNNING, STATE_COMPLETED, STATE_FAILED].freeze
 
     scope :for_source, ->(source) { where(source: source.to_s) }
+    scope :for_provider, ->(provider) { where(provider: provider.to_s) }
     scope :running, -> { where(state: STATE_RUNNING) }
     scope :completed, -> { where(state: STATE_COMPLETED) }
     scope :failed, -> { where(state: STATE_FAILED) }
     scope :latest, -> { order(started_at: :desc, id: :desc) }
 
-    def self.resume_cursor_for(source)
-      for_source(source).latest.limit(1).pick(:cursor)
+    def self.resume_cursor_for(source, provider: nil)
+      scope = for_source(source)
+      scope = scope.for_provider(provider) if provider
+      scope.latest.limit(1).pick(:cursor)
     end
 
-    def self.last_completed_window_for(source)
-      for_source(source).completed.latest.limit(1).pick(:window_start, :window_end)
+    def self.last_completed_window_for(source, provider: nil)
+      scope = for_source(source)
+      scope = scope.for_provider(provider) if provider
+      scope.completed.latest.limit(1).pick(:window_start, :window_end)
     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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "llm_cost_tracker/ledger"
+
+module LlmCostTracker
+  module Dashboard
+    module SetupState
+      SetupRequired = Data.define(:message, :details)
+      DOCS_HINT = "See docs/upgrading.md for the migration path."
+      MUTEX = Mutex.new
+
+      private_constant :MUTEX, :DOCS_HINT
+
+      class << self
+        def current
+          fingerprint = schema_fingerprint
+
+          MUTEX.synchronize do
+            if !defined?(@cache_fingerprint) || @cache_fingerprint != fingerprint
+              LlmCostTracker::Call.reset_column_information
+              @cached = compute
+              @cache_fingerprint = fingerprint
+            end
+          end
+          @cached
+        end
+
+        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?
+
+          core_drift = drift_in(schema_checks_for_current_config)
+          return core_drift if core_drift
+          return nil unless LlmCostTracker.reconciliation_enabled?
+
+          reconciliation_drift
+        end
+
+        def schema_checks_for_current_config
+          return LlmCostTracker::Ledger::Schema::CORE_SCHEMAS unless LlmCostTracker.configuration.cache_rollups
+
+          LlmCostTracker::Ledger::Schema::CORE_SCHEMAS + [LlmCostTracker::Ledger::Schema::CACHE_ROLLUPS_SCHEMA]
+        end
+
+        def drift_in(checks)
+          checks.each do |schema, table|
+            errors = schema.current_schema_errors
+            next if errors.empty?
+
+            message = "The #{table} table does not match the current LLM Cost Tracker schema."
+            return SetupRequired.new(message: message, details: errors)
+          end
+          nil
+        end
+
+        def reconciliation_drift
+          connection = ActiveRecord::Base.connection
+          LlmCostTracker::Reconciliation::SCHEMA_TABLES.each do |schema, table|
+            unless connection.data_source_exists?(table)
+              return SetupRequired.new(
+                message: "The #{table} table is required when reconciliation is enabled.",
+                details: ["bin/rails generate llm_cost_tracker:reconciliation && bin/rails db:migrate"]
+              )
+            end
+
+            errors = schema.current_schema_errors
+            next if errors.empty?
+
+            message = "The #{table} table does not match the current LLM Cost Tracker schema."
+            return SetupRequired.new(message: message, details: errors)
+          end
+          nil
+        end
+
+        def calls_table_missing
+          SetupRequired.new(
+            message: "The llm_cost_tracker_calls table is not available yet.",
+            details: nil
+          )
+        end
+      end
+    end
+  end
+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