llm_cost_tracker 0.5.2 → 0.5.3

data/lib/llm_cost_tracker/storage/custom_backend.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module LlmCostTracker
+  module Storage
+    class CustomBackend
+      class << self
+        def save(event)
+          result = LlmCostTracker.configuration.custom_storage&.call(event)
+          result == false ? false : event
+        end
+
+        def verify
+          if LlmCostTracker.configuration.custom_storage.respond_to?(:call)
+            return [
+              VerificationResult.new(
+                :ok,
+                "storage",
+                "custom storage callable configured; external sink was not invoked"
+              )
+            ]
+          end
+
+          [
+            VerificationResult.new(:error, "storage", "custom storage backend requires config.custom_storage")
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/storage/dispatcher.rb

@@ -1,18 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "../logging"
+require_relative "registry"
+require_relative "active_record_backend"
+require_relative "custom_backend"
+require_relative "log_backend"
 
 module LlmCostTracker
   module Storage
     class Dispatcher
       class << self
         def save(event)
-          config = LlmCostTracker.configuration
-          case config.storage_backend
-          when :log           then log_event(event, config)
-          when :active_record then active_record_save(event)
-          when :custom        then custom_save(event, config)
-          end
+          backend.save(event)
         rescue LlmCostTracker::BudgetExceededError, LlmCostTracker::UnknownPricingError
           raise
         rescue StandardError => e
@@ -22,34 +21,8 @@ module LlmCostTracker
 
         private
 
-        def log_event(event, config)
-          message = "#{event.provider}/#{event.model} " \
-                    "tokens=#{event.total_tokens} " \
-                    "cost=#{log_cost_label(event)}"
-          message += " latency=#{event.latency_ms}ms" if event.latency_ms
-          message += " stream=#{event.stream}" if event.stream
-          message += " source=#{event.usage_source}" if event.usage_source
-          message += " tags=#{event.tags}" unless event.tags.empty?
-
-          Logging.log(config.log_level, message)
-          event
-        end
-
-        def log_cost_label(event) = event.cost ? "$#{format('%.6f', event.cost.total_cost)}" : "unknown"
-
-        def active_record_save(event)
-          require_relative "../llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
-          require_relative "active_record_store" unless defined?(LlmCostTracker::Storage::ActiveRecordStore)
-
-          ActiveRecordStore.save(event)
-          event
-        rescue LoadError => e
-          raise Error, "ActiveRecord storage requires the active_record gem: #{e.message}"
-        end
-
-        def custom_save(event, config)
-          result = config.custom_storage&.call(event)
-          result == false ? false : event
+        def backend
+          Registry.fetch(LlmCostTracker.configuration.storage_backend)
         end
 
         def handle_error(error)
@@ -64,5 +37,9 @@ module LlmCostTracker
         end
       end
     end
+
+    Registry.register(:log, LogBackend)
+    Registry.register(:active_record, ActiveRecordBackend)
+    Registry.register(:custom, CustomBackend)
   end
 end

data/lib/llm_cost_tracker/storage/log_backend.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../logging"
+require_relative "registry"
+
+module LlmCostTracker
+  module Storage
+    class LogBackend
+      class << self
+        def save(event)
+          config = LlmCostTracker.configuration
+          message = "#{event.provider}/#{event.model} " \
+                    "tokens=#{event.total_tokens} " \
+                    "cost=#{cost_label(event)}"
+          message += " latency=#{event.latency_ms}ms" if event.latency_ms
+          message += " stream=#{event.stream}" if event.stream
+          message += " source=#{event.usage_source}" if event.usage_source
+          message += " tags=#{event.tags}" unless event.tags.empty?
+
+          Logging.log(config.log_level, message)
+          event
+        end
+
+        def verify
+          [
+            VerificationResult.new(:ok, "storage", "log backend configured; capture writes to logs only")
+          ]
+        end
+
+        private
+
+        def cost_label(event)
+          event.cost ? "$#{format('%.6f', event.cost.total_cost)}" : "unknown"
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/storage/registry.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+require_relative "../errors"
+
+module LlmCostTracker
+  module Storage
+    VerificationResult = Data.define(:status, :name, :message)
+
+    module Registry
+      MUTEX = Monitor.new
+
+      class << self
+        def register(name, backend)
+          name = normalize_name(name)
+          validate_backend!(backend)
+          MUTEX.synchronize { @backends = backends.merge(name => backend).freeze }
+          backend
+        end
+
+        def fetch(name)
+          key = normalize_name(name)
+          backends.fetch(key) do
+            raise Error, "Unknown storage_backend: #{key.inspect}. Use one of: #{names.join(', ')}"
+          end
+        end
+
+        def registered?(name)
+          backends.key?(normalize_name(name))
+        end
+
+        def names
+          backends.keys
+        end
+
+        private
+
+        def backends
+          @backends || MUTEX.synchronize { @backends ||= {}.freeze }
+        end
+
+        def normalize_name(name)
+          name.to_sym
+        end
+
+        def validate_backend!(backend)
+          return if backend.respond_to?(:save)
+
+          raise ArgumentError, "storage backend must respond to save"
+        end
+      end
+    end
+
+    def self.register(name, backend)
+      Registry.register(name, backend)
+    end
+
+    def self.backends
+      Registry.names
+    end
+  end
+end

data/lib/llm_cost_tracker/tag_sql.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "tag_key"
+
+module LlmCostTracker
+  module TagSql
+    class << self
+      def value_expression(model, key, table_name:)
+        key = TagKey.validate!(key)
+        column = "#{table_name}.#{model.connection.quote_column_name('tags')}"
+
+        case model.connection.adapter_name
+        when /postgres/i
+          json_column = model.tags_jsonb_column? ? column : "(#{column})::jsonb"
+          "#{json_column}->>#{model.connection.quote(key)}"
+        when /mysql/i
+          "JSON_UNQUOTE(JSON_EXTRACT(#{column}, #{model.connection.quote(json_path(key))}))"
+        else
+          "json_extract(#{column}, #{model.connection.quote(json_path(key))})"
+        end
+      end
+
+      def value_label(value)
+        value.nil? || value == "" ? "(untagged)" : value.to_s
+      end
+
+      private
+
+      def json_path(key)
+        "$.\"#{key}\""
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmCostTracker
-  VERSION = "0.5.2"
+  VERSION = "0.5.3"
 end

data/lib/llm_cost_tracker.rb

@@ -33,14 +33,17 @@ require_relative "llm_cost_tracker/tag_context"
 require_relative "llm_cost_tracker/tag_sanitizer"
 require_relative "llm_cost_tracker/tags_column"
 require_relative "llm_cost_tracker/tag_key"
+require_relative "llm_cost_tracker/tag_sql"
 require_relative "llm_cost_tracker/tag_query"
 require_relative "llm_cost_tracker/tag_accessors"
+require_relative "llm_cost_tracker/llm_api_call_metrics"
 require_relative "llm_cost_tracker/tracker"
 require_relative "llm_cost_tracker/retention"
 require_relative "llm_cost_tracker/report_data"
 require_relative "llm_cost_tracker/report_formatter"
 require_relative "llm_cost_tracker/report"
 require_relative "llm_cost_tracker/doctor"
+require_relative "llm_cost_tracker/capture_verifier"
 
 module LlmCostTracker
   CONFIGURATION_MUTEX = Monitor.new

data/lib/tasks/llm_cost_tracker.rake

@@ -7,11 +7,21 @@ namespace :llm_cost_tracker do
   desc "Check LLM Cost Tracker setup"
   task :doctor do
     Rake::Task["environment"].invoke if Rake::Task.task_defined?("environment")
+    require_relative "../llm_cost_tracker"
     checks = LlmCostTracker::Doctor.call
     puts LlmCostTracker::Doctor.report(checks)
     abort("llm_cost_tracker: doctor found setup errors") unless LlmCostTracker::Doctor.healthy?(checks)
   end
 
+  desc "Verify that LLM Cost Tracker can capture and persist a synthetic event"
+  task :verify_capture do
+    Rake::Task["environment"].invoke if Rake::Task.task_defined?("environment")
+    require_relative "../llm_cost_tracker"
+    checks = LlmCostTracker::CaptureVerifier.call
+    puts LlmCostTracker::CaptureVerifier.report(checks)
+    abort("llm_cost_tracker: capture verification failed") unless LlmCostTracker::CaptureVerifier.healthy?(checks)
+  end
+
   desc "Print an LLM cost report from ActiveRecord storage"
   task report: :environment do
     days = (ENV["DAYS"] || LlmCostTracker::Report::DEFAULT_DAYS).to_i
@@ -74,6 +84,17 @@ namespace :llm_cost_tracker do
       puts "  pricing is up to date" if result.up_to_date
       abort("llm_cost_tracker: pricing check failed") unless result.up_to_date
     end
+
+    desc "Explain how a provider/model price is matched. Use PROVIDER=... MODEL=..."
+    task :explain do
+      Rake::Task["environment"].invoke if Rake::Task.task_defined?("environment")
+      require_relative "../llm_cost_tracker"
+
+      explanation = price_explanation_from_env
+      puts "llm_cost_tracker: #{explanation.message}"
+      print_price_explanation(explanation)
+      abort("llm_cost_tracker: price is incomplete or unknown") unless explanation.complete?
+    end
   end
 end
 # rubocop:enable Metrics/BlockLength
@@ -95,3 +116,31 @@ def price_refresh_output_path
   FileUtils.mkdir_p(File.dirname(path))
   path
 end
+
+def price_explanation_from_env
+  provider = ENV["PROVIDER"].to_s.strip
+  model = ENV["MODEL"].to_s.strip
+  abort("llm_cost_tracker: use PROVIDER=... MODEL=...") if provider.empty? || model.empty?
+
+  LlmCostTracker::Pricing.explain(
+    provider: provider,
+    model: model,
+    pricing_mode: ENV.fetch("PRICING_MODE", nil),
+    input_tokens: ENV.fetch("INPUT_TOKENS", 1).to_i,
+    output_tokens: ENV.fetch("OUTPUT_TOKENS", 1).to_i,
+    cache_read_input_tokens: ENV.fetch("CACHE_READ_INPUT_TOKENS", 0).to_i,
+    cache_write_input_tokens: ENV.fetch("CACHE_WRITE_INPUT_TOKENS", 0).to_i
+  )
+end
+
+def print_price_explanation(explanation)
+  return unless explanation.matched?
+
+  puts "  source: #{explanation.source}"
+  puts "  matched_key: #{explanation.matched_key}"
+  puts "  matched_by: #{explanation.matched_by}"
+  puts "  pricing_mode: #{explanation.pricing_mode || 'standard'}"
+  explanation.effective_prices.each do |key, value|
+    puts "  #{key}: #{value.nil? ? 'missing' : value}"
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm_cost_tracker
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.3
 platform: ruby
 authors:
 - Sergii Khomenko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -283,13 +283,33 @@ files:
 - app/views/llm_cost_tracker/tags/index.html.erb
 - app/views/llm_cost_tracker/tags/show.html.erb
 - config/routes.rb
+- docs/architecture.md
+- docs/budgets.md
+- docs/configuration.md
+- docs/cookbook.md
+- docs/dashboard-overview.png
+- docs/dashboard.md
+- docs/extending.md
+- docs/operations.md
+- docs/pricing.md
+- docs/querying.md
+- docs/streaming.md
+- docs/technical/README.md
+- docs/technical/data-flow.md
+- docs/technical/extension-points.md
+- docs/technical/module-map.md
+- docs/technical/operational-notes.md
+- docs/upgrading.md
 - lib/llm_cost_tracker.rb
 - lib/llm_cost_tracker/assets.rb
 - lib/llm_cost_tracker/budget.rb
+- lib/llm_cost_tracker/capture_verifier.rb
 - lib/llm_cost_tracker/configuration.rb
 - lib/llm_cost_tracker/configuration/instrumentation.rb
+- lib/llm_cost_tracker/configuration/storage_backend.rb
 - lib/llm_cost_tracker/cost.rb
 - lib/llm_cost_tracker/doctor.rb
+- lib/llm_cost_tracker/doctor/capture_check.rb
 - lib/llm_cost_tracker/engine.rb
 - lib/llm_cost_tracker/engine_compatibility.rb
 - lib/llm_cost_tracker/errors.rb
@@ -319,7 +339,9 @@ files:
 - lib/llm_cost_tracker/integrations/openai.rb
 - lib/llm_cost_tracker/integrations/registry.rb
 - lib/llm_cost_tracker/integrations/ruby_llm.rb
+- lib/llm_cost_tracker/integrations/stream_tracker.rb
 - lib/llm_cost_tracker/llm_api_call.rb
+- lib/llm_cost_tracker/llm_api_call_metrics.rb
 - lib/llm_cost_tracker/logging.rb
 - lib/llm_cost_tracker/middleware/faraday.rb
 - lib/llm_cost_tracker/parameter_hash.rb
@@ -343,15 +365,22 @@ files:
 - lib/llm_cost_tracker/price_sync/registry_writer.rb
 - lib/llm_cost_tracker/prices.json
 - lib/llm_cost_tracker/pricing.rb
+- lib/llm_cost_tracker/pricing/effective_prices.rb
+- lib/llm_cost_tracker/pricing/explainer.rb
+- lib/llm_cost_tracker/pricing/lookup.rb
 - lib/llm_cost_tracker/railtie.rb
 - lib/llm_cost_tracker/report.rb
 - lib/llm_cost_tracker/report_data.rb
 - lib/llm_cost_tracker/report_formatter.rb
 - lib/llm_cost_tracker/request_url.rb
 - lib/llm_cost_tracker/retention.rb
+- lib/llm_cost_tracker/storage/active_record_backend.rb
 - lib/llm_cost_tracker/storage/active_record_rollups.rb
 - lib/llm_cost_tracker/storage/active_record_store.rb
+- lib/llm_cost_tracker/storage/custom_backend.rb
 - lib/llm_cost_tracker/storage/dispatcher.rb
+- lib/llm_cost_tracker/storage/log_backend.rb
+- lib/llm_cost_tracker/storage/registry.rb
 - lib/llm_cost_tracker/stream_capture.rb
 - lib/llm_cost_tracker/stream_collector.rb
 - lib/llm_cost_tracker/tag_accessors.rb
@@ -359,6 +388,7 @@ files:
 - lib/llm_cost_tracker/tag_key.rb
 - lib/llm_cost_tracker/tag_query.rb
 - lib/llm_cost_tracker/tag_sanitizer.rb
+- lib/llm_cost_tracker/tag_sql.rb
 - lib/llm_cost_tracker/tags_column.rb
 - lib/llm_cost_tracker/tracker.rb
 - lib/llm_cost_tracker/unknown_pricing.rb