llm_cost_tracker 0.7.3 → 0.9.0

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -19,9 +19,10 @@ module LlmCostTracker
         format.html do
           @page = Dashboard::Pagination.call(params)
           @calls_count = scope.count
-          @calls = ordered_scope.limit(@page.limit).offset(@page.offset).to_a
+          @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)),
                     type: "text/csv",
                     disposition: %(attachment; filename="llm_calls_#{Time.now.utc.strftime('%Y%m%d_%H%M%S')}.csv")
@@ -30,7 +31,7 @@ module LlmCostTracker
     end
 
     def show
-      @call = Ledger::Call.find(params[:id])
+      @call = LlmCostTracker::Call.find(params[:id])
     end
 
     private
@@ -55,38 +56,40 @@ module LlmCostTracker
       CSV.generate do |csv|
         csv << fields.map(&:to_s)
 
-        relation.pluck(*fields).each do |values|
-          csv << fields.zip(values).map { |field, value| csv_value(field, value) }
+        relation.includes(:tag_records).each do |call|
+          csv << fields.map { |field| csv_value(field, call) }
         end
       end
     end
 
     def csv_fields
       %i[tracked_at provider model] +
-        TokenUsage::STORED_KEYS +
-        Pricing::COST_KEYS +
-        %i[latency_ms provider_response_id tags]
+        TokenUsage.members +
+        %i[
+          total_cost cost_status pricing_snapshot latency_ms provider_response_id provider_project_id
+          provider_api_key_id provider_workspace_id batch tags
+        ]
     end
 
-    def csv_value(field, value)
+    def csv_value(field, call)
       case field
       when :tracked_at
-        value&.utc&.iso8601
-      when :provider, :model, :provider_response_id
-        csv_safe(value)
+        call.tracked_at&.utc&.iso8601
+      when :provider_api_key_id, :provider_workspace_id, :provider_project_id
+        csv_safe(LlmCostTracker::Masking.mask_value(field, call[field]))
+      when :provider, :model, :provider_response_id, :cost_status
+        csv_safe(call[field])
+      when :pricing_snapshot
+        csv_safe(csv_json(call.pricing_snapshot))
       when :tags
-        csv_safe(csv_tags(value))
+        csv_safe(call.parsed_tags.to_json)
       else
-        value
+        call[field]
       end
     end
 
-    def csv_tags(value)
-      return value.transform_keys(&:to_s).to_json if value.is_a?(Hash)
-
-      JSON.parse(value || "{}").to_json
-    rescue JSON::ParserError
-      "{}"
+    def csv_json(value)
+      Hash(value).deep_stringify_keys.to_json
     end
 
     def csv_safe(value)

data/app/controllers/llm_cost_tracker/data_quality_controller.rb

@@ -5,9 +5,21 @@ module LlmCostTracker
     def index
       scope = Dashboard::Filter.call(params: params)
       @stats = Dashboard::DataQuality.call(scope: scope)
-      @usage_rows = Dashboard::DataQuality.usage_rows(@stats)
+      @summary = Dashboard::DataQuality.summary(@stats)
+      @usage_rows = Dashboard::DataQuality.usage_rows(
+        @stats,
+        component_costs: Dashboard::DataQuality.component_costs(scope)
+      )
       @hidden_output_summary = Dashboard::DataQuality.hidden_output_summary(@stats)
-      @unknown_pricing_by_model = Dashboard::DataQuality.unknown_pricing_by_model(scope)
+      @unknown_pricing_by_model = Dashboard::DataQuality.unknown_pricing_by_model(
+        scope,
+        total_calls: @summary.total
+      )
+      @service_charge_rows = Dashboard::DataQuality.service_charge_rows(scope).to_a
+      @streaming_health_rows = Dashboard::DataQuality.streaming_health_rows(
+        scope,
+        total_streaming: @summary.streaming_count
+      )
     end
   end
 end

data/app/controllers/llm_cost_tracker/reconciliation_controller.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  class ReconciliationController < ApplicationController
+    def index
+      @reconciliation_enabled = LlmCostTracker::Reconciliation.enabled?
+      @reconciliation_installed = LlmCostTracker::ProviderInvoice.table_exists?
+      if @reconciliation_enabled && @reconciliation_installed
+        @scopes = invoice_scopes
+        @sources = @scopes.map { |scope| scope[:source] }.uniq
+        @diffs = @scopes.filter_map { |scope| diff_for(scope) }
+        @last_imported_at = LlmCostTracker::ProviderInvoice.maximum(:imported_at)
+      else
+        @scopes = []
+        @sources = []
+        @diffs = []
+        @last_imported_at = nil
+      end
+      @threshold = LlmCostTracker::Reconciliation::DEFAULT_THRESHOLD_PERCENT
+      @configured_importers = @reconciliation_enabled ? configured_importers : {}
+    end
+
+    def trigger_import
+      unless LlmCostTracker::Reconciliation.enabled?
+        return redirect_to reconciliation_path, alert: "Reconciliation is disabled"
+      end
+
+      source = params[:source].to_s
+      importer = configured_importers[source.to_sym]
+      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?
+        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."
+        )
+      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
+    rescue StandardError => e
+      LlmCostTracker::Logging.warn("Reconciliation import failed for #{source}: #{e.class}: #{e.message}")
+      redirect_to reconciliation_path,
+                  alert: "Import failed (#{e.class.name}); see Rails logs for details."
+    end
+
+    private
+
+    def configured_importers
+      LlmCostTracker.configuration.reconciliation_importers
+    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
+      LlmCostTracker::ProviderInvoice
+        .group(:source, provider_expr, :currency)
+        .order(:source, :currency)
+        .pluck(:source, provider_expr, :currency)
+        .map { |source, provider, currency| { source: source, provider: provider, currency: currency.upcase } }
+    end
+
+    def diff_for(scope)
+      window = scope_invoices(scope)
+               .order(period_end: :desc, period_start: :desc)
+               .limit(1)
+               .pick(:period_start, :period_end)
+      return nil unless window
+
+      LlmCostTracker::Reconciliation.diff(
+        source: scope[:source], provider: scope[:provider], currency: scope[:currency],
+        period_start: window[0], period_end: window[1]
+      )
+    rescue ArgumentError => e
+      LlmCostTracker::Logging.warn("Reconciliation diff skipped for #{scope.inspect}: #{e.message}")
+      nil
+    end
+
+    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?
+
+      if LlmCostTracker::Ledger::Schema::Adapter.postgresql?(connection)
+        relation.where("metadata->>'provider' = ?", provider)
+      else
+        relation.where("JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.provider')) = ?", provider)
+      end
+    end
+  end
+end

data/app/controllers/llm_cost_tracker/tags_controller.rb

@@ -7,7 +7,21 @@ module LlmCostTracker
     end
 
     def show
-      @breakdown = Dashboard::TagBreakdown.call(scope: Dashboard::Filter.call(params: params), key: params[:key])
+      scope = Dashboard::Filter.call(params: params)
+      @value = params[:tag_value].to_s
+
+      if @value.empty?
+        @breakdown = Dashboard::TagBreakdown.call(scope: scope, key: params[:key])
+      else
+        @key = LlmCostTracker::Tags::Key.validate!(
+          params[:key],
+          error_class: LlmCostTracker::InvalidFilterError
+        )
+        value_scope = scope.by_tag(@key, @value)
+        @value_total_cost = value_scope.sum(:total_cost).to_f
+        @value_calls = value_scope.count
+        @value_points = Dashboard::TimeSeries.call(scope: value_scope)
+      end
     end
   end
 end

data/app/helpers/llm_cost_tracker/application_helper.rb

@@ -13,9 +13,11 @@ module LlmCostTracker
     include ChartHelper
     include PaginationHelper
     include TokenUsageHelper
+    include InlineStyleHelper
 
     def coverage_percent(numerator, denominator)
-      return 0.0 unless denominator.to_i.positive?
+      denominator = denominator.to_f
+      return 0.0 unless denominator.positive?
 
       (numerator.to_f / denominator) * 100.0
     end
@@ -39,16 +41,19 @@ module LlmCostTracker
       number_with_delimiter(value.to_i)
     end
 
-    def format_tokens(value)
-      number(value)
-    end
-
     def format_date(value)
       value.try(:strftime, "%Y-%m-%d %H:%M") || value.to_s
     end
 
     def pricing_status(call)
-      call.total_cost.nil? ? "Unknown pricing" : "Estimated"
+      return "Unknown pricing" 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")
     end
 
     def percent(value)
@@ -100,13 +105,13 @@ module LlmCostTracker
       value.to_s
     end
 
-    def tags_summary(tags, limit: 3)
-      tags = normalized_tags(tags)
-      return "(untagged)" if tags.empty?
+    def masked_metadata_hash(value)
+      return value if value.is_a?(Hash)
+      return {} if value.nil?
 
-      summary = tags.first(limit).map { |key, value| "#{key}=#{tag_value_summary(value)}" }
-      summary << "+#{tags.size - limit}" if tags.size > limit
-      summary.join(", ")
+      JSON.parse(value.to_s)
+    rescue JSON::ParserError, TypeError
+      {}
     end
 
     def tag_chip_entries(tags, limit: 3)
@@ -124,14 +129,6 @@ module LlmCostTracker
       truncate_text(safe_json(tags), TAG_TOOLTIP_BYTES)
     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
@@ -164,7 +161,7 @@ module LlmCostTracker
     def truncate_text(string, limit)
       return string if string.bytesize <= limit
 
-      "#{string.byteslice(0, limit).to_s.encode('UTF-8', invalid: :replace, undef: :replace)}..."
+      "#{string.byteslice(0, limit).encode('UTF-8', invalid: :replace, undef: :replace)}..."
     end
   end
 end

data/app/helpers/llm_cost_tracker/dashboard_filter_helper.rb

@@ -2,7 +2,7 @@
 
 module LlmCostTracker
   module DashboardFilterHelper
-    FILTER_PARAM_KEYS = %i[from to provider model stream usage_source tag sort page per].freeze
+    FILTER_PARAM_KEYS = %i[from to provider model stream usage_source tag].freeze
 
     STREAM_FILTER_OPTIONS = [
       ["Streaming only", "yes"],
@@ -14,33 +14,15 @@ module LlmCostTracker
     end
 
     def active_tag_filters
-      tag_params = LlmCostTracker::Dashboard::Params.to_hash(params[:tag]).transform_keys(&:to_s).transform_values(&:to_s)
+      tag_params = LlmCostTracker::Dashboard::Params.tag_query(params[:tag])
 
       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))
+          path: dashboard_filter_path(current_query(tag: tag_params.except(key).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

@@ -15,14 +15,14 @@ module LlmCostTracker
     private
 
     def filter_options_for(column, filter_params:)
-      source = LlmCostTracker::Dashboard::Params.to_hash(filter_params)
-      scope_params = source.stringify_keys.merge(
-        column.to_s => nil, "format" => nil, "page" => nil, "per" => nil, "sort" => nil
+      source = LlmCostTracker::Dashboard::Params.to_hash(filter_params).symbolize_keys
+      scope_params = source.merge(
+        column => nil, format: nil, page: nil, per: nil, sort: nil
       )
       values = LlmCostTracker::Dashboard::Filter.call(params: scope_params)
                                                 .where.not(column => [nil, ""])
                                                 .distinct.order(column).limit(MAX_FILTER_OPTIONS).pluck(column)
-      current = source[column.to_s].presence || source[column].presence
+      current = source[column].presence
       values.unshift(current) if current && !values.include?(current)
       values
     end

data/app/helpers/llm_cost_tracker/dashboard_query_helper.rb

@@ -11,7 +11,7 @@ module LlmCostTracker
 
     def calls_query_for_tag(key:, value:)
       query = current_query(page: nil, per: nil, format: nil)
-      tags = LlmCostTracker::Dashboard::Params.to_hash(query[:tag]).transform_keys(&:to_s).transform_values(&:to_s)
+      tags = LlmCostTracker::Dashboard::Params.tag_query(query[:tag])
       query[:tag] = tags.merge(key.to_s => value.to_s)
       query
     end

data/app/helpers/llm_cost_tracker/inline_style_helper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module InlineStyleHelper
+    UNSAFE_CSS_CHARS = /[<>{}"]/
+
+    def inline_style(declarations)
+      registry = inline_style_registry
+      token = "lct-i-#{registry.length}"
+      registry << [token, declarations.to_s.gsub(UNSAFE_CSS_CHARS, "")]
+      token
+    end
+
+    def inline_style_block
+      registry = inline_style_registry
+      return "".html_safe if registry.empty?
+
+      rules = registry.map { |token, decl| %([data-lct-style="#{token}"]{#{decl}}) }.join("\n")
+      content_tag(:style, rules.html_safe, nonce: dashboard_csp_nonce)
+    end
+
+    private
+
+    def inline_style_registry
+      @inline_style_registry ||= []
+    end
+  end
+end

data/app/helpers/llm_cost_tracker/reconciliation_helper.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module ReconciliationHelper
+    def attribution_summary(attribution)
+      LlmCostTracker::Masking.format_attribution(attribution)
+    end
+
+    def mask_secret(value)
+      LlmCostTracker::Masking.mask_value(:provider_api_key_id, value)
+    end
+  end
+end

data/app/helpers/llm_cost_tracker/token_usage_helper.rb

@@ -6,22 +6,30 @@ module LlmCostTracker
       input_tokens: "Input",
       cache_read_input_tokens: "Cache read",
       cache_write_input_tokens: "Cache write",
-      cache_write_1h_input_tokens: "1h cache write",
+      cache_write_extended_input_tokens: "Extended cache write",
+      audio_input_tokens: "Audio input",
+      image_input_tokens: "Image input",
       output_tokens: "Output",
+      audio_output_tokens: "Audio output",
+      image_output_tokens: "Image output",
       hidden_output_tokens: "Hidden output"
     }.freeze
     QUALITY_LABELS = COMPONENT_LABELS.merge(
       input_tokens: "Regular input",
       cache_read_input_tokens: "Cache read input",
       cache_write_input_tokens: "Cache write input",
-      cache_write_1h_input_tokens: "1h cache write input"
+      cache_write_extended_input_tokens: "Extended cache write input"
     ).freeze
     STACK_CLASSES = {
       input_tokens: "lct-stack-fill-input",
       cache_read_input_tokens: "lct-stack-fill-cache-read",
       cache_write_input_tokens: "lct-stack-fill-cache-write",
-      cache_write_1h_input_tokens: "lct-stack-fill-cache-write-1h",
-      output_tokens: "lct-stack-fill-output"
+      cache_write_extended_input_tokens: "lct-stack-fill-cache-write-extended",
+      audio_input_tokens: "lct-stack-fill-audio-input",
+      image_input_tokens: "lct-stack-fill-image-input",
+      output_tokens: "lct-stack-fill-output",
+      audio_output_tokens: "lct-stack-fill-audio-output",
+      image_output_tokens: "lct-stack-fill-image-output"
     }.freeze
 
     def token_usage_stack_components
@@ -30,18 +38,26 @@ module LlmCostTracker
       end
     end
 
-    def token_usage_quality_label(token_key)
-      QUALITY_LABELS.fetch(token_key.to_sym)
+    def call_line_item_costs_by_component(call)
+      call.line_items.each_with_object({}) do |line_item, accumulator|
+        component = LlmCostTracker::Billing::Components::TOKEN_PRICED.find do |item|
+          item.kind.to_s == line_item.kind.to_s &&
+            item.direction.to_s == line_item.direction.to_s &&
+            item.cache_state.to_s == line_item.cache_state.to_s
+        end
+        accumulator[component.key] = line_item.cost if component && line_item.cost
+      end
     end
 
     private
 
     def token_usage_display_components(labels:)
-      LlmCostTracker::Pricing::COMPONENTS.map do |component|
+      LlmCostTracker::Billing::Components::TOKEN_PRICED.map do |component|
         token_key = component.token_key
         {
           token_key: token_key,
           cost_key: component.cost_key,
+          price_key: component.key,
           label: labels.fetch(token_key),
           css_class: STACK_CLASSES[token_key]
         }
@@ -49,6 +65,7 @@ module LlmCostTracker
         {
           token_key: :hidden_output_tokens,
           cost_key: nil,
+          price_key: nil,
           label: labels.fetch(:hidden_output_tokens),
           css_class: nil
         }

data/app/models/llm_cost_tracker/call.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require "llm_cost_tracker/billing/cost_status"
+require "llm_cost_tracker/ledger/schema/adapter"
+require "llm_cost_tracker/ledger/tags/sql"
+
+module LlmCostTracker
+  class Call < ActiveRecord::Base
+    before_validation :assign_event_id
+
+    PERIOD_FORMATS = {
+      day: {
+        postgres: "YYYY-MM-DD",
+        mysql: "%Y-%m-%d"
+      },
+      month: {
+        postgres: "YYYY-MM",
+        mysql: "%Y-%m"
+      }
+    }.freeze
+
+    private_constant :PERIOD_FORMATS
+
+    scope :with_cost, -> { where.not(total_cost: nil) }
+    scope :without_cost, -> { where(total_cost: nil) }
+    scope :unknown_pricing, lambda {
+      where(total_cost: nil).or(
+        where(cost_status: [Billing::CostStatus::UNKNOWN, Billing::CostStatus::PARTIAL])
+      )
+    }
+    scope :with_latency, -> { where.not(latency_ms: nil) }
+    scope :streaming,     -> { where(stream: true) }
+    scope :non_streaming, -> { where(stream: [false, nil]) }
+    scope :by_usage_source, ->(source) { where(usage_source: source.to_s) }
+    scope :with_provider_response_id, -> { where.not(provider_response_id: [nil, ""]) }
+    scope :missing_provider_response_id, -> { where(provider_response_id: [nil, ""]) }
+    scope :streaming_missing_usage, lambda {
+      where(stream: true).where(usage_source: ["unknown", nil])
+    }
+
+    has_many :line_items,
+             class_name: "LlmCostTracker::CallLineItem",
+             foreign_key: :llm_cost_tracker_call_id,
+             inverse_of: :call,
+             dependent: :delete_all
+
+    has_many :tag_records,
+             class_name: "LlmCostTracker::CallTag",
+             foreign_key: :llm_cost_tracker_call_id,
+             inverse_of: :call,
+             dependent: :delete_all
+
+    scope :today,       -> { where(tracked_at: Time.now.utc.beginning_of_day..) }
+    scope :this_week,   -> { where(tracked_at: Time.now.utc.beginning_of_week..) }
+    scope :this_month,  -> { where(tracked_at: Time.now.utc.beginning_of_month..) }
+    scope :between,     ->(from, to) { where(tracked_at: from..to) }
+
+    class << self
+      def by_tag(key, value) = by_tags(key => value)
+
+      def by_tags(tags) = Ledger::Tags::Query.apply(tags)
+
+      def total_cost = sum(:total_cost).to_f
+
+      def total_tokens = sum(:total_tokens).to_i
+
+      def cost_by_model(limit: nil) = cost_by_column(:model, limit: limit)
+
+      def cost_by_provider(limit: nil) = cost_by_column(:provider, limit: limit)
+
+      def group_by_tag(key)
+        Ledger::Tags::Sql.join_relation(self, key).group(Ledger::Tags::Sql.value_arel)
+      end
+
+      def cost_by_tag(key, limit: nil)
+        label = Ledger::Tags::Sql.label_sql(connection)
+        raw_value = Ledger::Tags::Sql.raw_value_sql(connection)
+        relation = Ledger::Tags::Sql.join_relation(self, key)
+                                    .select("#{label} AS name", "COALESCE(SUM(total_cost), 0) AS total_cost")
+                                    .group(Arel.sql(label))
+                                    .order(
+                                      Arel.sql("COALESCE(SUM(total_cost), 0) DESC"),
+                                      Arel.sql("MAX(CASE WHEN #{raw_value} IS NULL THEN 1 ELSE 0 END) ASC"),
+                                      Arel.sql("#{label} DESC")
+                                    )
+        relation = relation.limit(limit) if limit
+        relation
+      end
+
+      def average_latency_ms = average(:latency_ms)&.to_f
+
+      def latency_by_model = group(:model).average(:latency_ms).transform_values(&:to_f)
+
+      def latency_by_provider = group(:provider).average(:latency_ms).transform_values(&:to_f)
+
+      def group_by_period(period, column: :tracked_at)
+        group(Arel.sql(period_group_expression(period, column: column)))
+      end
+
+      def daily_costs(days: 30)
+        where(tracked_at: days.days.ago..)
+          .group_by_period(:day)
+          .sum(:total_cost)
+      end
+
+      private
+
+      def cost_by_column(column, limit:)
+        quoted_column = "#{quoted_table_name}.#{connection.quote_column_name(column)}"
+        relation = select("#{quoted_column} AS name, COALESCE(SUM(total_cost), 0) AS total_cost")
+                   .group(column)
+                   .order(Arel.sql("COALESCE(SUM(total_cost), 0) DESC"))
+        relation = relation.limit(limit) if limit
+        relation
+      end
+
+      def period_group_expression(period, column:)
+        period = validated_period(period)
+        column = period_column_expression(column)
+        formats = PERIOD_FORMATS.fetch(period)
+
+        if Ledger::Schema::Adapter.postgresql?(connection)
+          postgres_period_expression(period, column, formats)
+        elsif Ledger::Schema::Adapter.mysql?(connection)
+          "DATE_FORMAT(#{column}, #{connection.quote(formats.fetch(:mysql))})"
+        else
+          Ledger::Schema::Adapter.ensure_supported!(connection)
+        end
+      end
+
+      def postgres_period_expression(period, column, formats)
+        "TO_CHAR(" \
+          "DATE_TRUNC(#{connection.quote(period.name)}, #{column}), " \
+          "#{connection.quote(formats.fetch(:postgres))}" \
+          ")"
+      end
+
+      def validated_period(period)
+        return period if PERIOD_FORMATS.key?(period)
+
+        raise ArgumentError, "invalid period: #{period.inspect}"
+      end
+
+      def period_column_expression(column)
+        column = column.to_s
+        return "#{quoted_table_name}.#{connection.quote_column_name(column)}" if column_names.include?(column)
+
+        raise ArgumentError, "invalid period column: #{column.inspect}"
+      end
+    end
+
+    def parsed_tags
+      tag_records.to_h do |record|
+        [record.key, record.value]
+      end
+    end
+
+    private
+
+    def assign_event_id
+      self.event_id ||= SecureRandom.uuid
+    end
+  end
+end