llm_cost_tracker 0.5.2 → 0.6.0

data/lib/llm_cost_tracker.rb

@@ -31,16 +31,20 @@ require_relative "llm_cost_tracker/unknown_pricing"
 require_relative "llm_cost_tracker/event_metadata"
 require_relative "llm_cost_tracker/tag_context"
 require_relative "llm_cost_tracker/tag_sanitizer"
+require_relative "llm_cost_tracker/active_record_adapter"
 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
@@ -50,6 +54,10 @@ module LlmCostTracker
       CONFIGURATION_MUTEX.synchronize { @configuration ||= Configuration.new }
     end
 
+    def configuration_generation
+      CONFIGURATION_MUTEX.synchronize { @configuration_generation ||= 0 }
+    end
+
     def configure
       config = CONFIGURATION_MUTEX.synchronize do
         current = @configuration || Configuration.new
@@ -58,6 +66,7 @@ module LlmCostTracker
         yield(current)
         current.openai_compatible_providers = current.openai_compatible_providers.dup
         current.finalize!
+        @configuration_generation = @configuration_generation.to_i + 1
         current
       end
       Integrations.install!
@@ -65,12 +74,39 @@ module LlmCostTracker
     end
 
     def reset_configuration!
-      CONFIGURATION_MUTEX.synchronize { @configuration = Configuration.new }
+      Storage::ActiveRecordInbox.reset! if defined?(Storage::ActiveRecordInbox)
+      Storage::ActiveRecordIngestor.shutdown!(drain: false) if defined?(Storage::ActiveRecordIngestor)
+      CONFIGURATION_MUTEX.synchronize do
+        @configuration = Configuration.new
+        @configuration_generation = @configuration_generation.to_i + 1
+      end
       UnknownPricing.reset! if defined?(UnknownPricing)
       Storage::ActiveRecordStore.reset! if defined?(Storage::ActiveRecordStore)
+      Storage::ActiveRecordInbox.reset! if defined?(Storage::ActiveRecordInbox)
+      Storage::ActiveRecordIngestor.reset! if defined?(Storage::ActiveRecordIngestor)
       TagContext.clear! if defined?(TagContext)
     end
 
+    def flush!(timeout: nil)
+      return true unless defined?(Storage::ActiveRecordIngestor)
+
+      if timeout
+        Storage::ActiveRecordIngestor.flush!(timeout: timeout)
+      else
+        Storage::ActiveRecordIngestor.flush!
+      end
+    end
+
+    def shutdown!(timeout: nil, drain: true)
+      return true unless defined?(Storage::ActiveRecordIngestor)
+
+      if timeout
+        Storage::ActiveRecordIngestor.shutdown!(timeout: timeout, drain: drain)
+      else
+        Storage::ActiveRecordIngestor.shutdown!(drain: drain)
+      end
+    end
+
     def enforce_budget!
       Tracker.enforce_budget!
     end
@@ -137,3 +173,5 @@ if defined?(Faraday)
     llm_cost_tracker: LlmCostTracker::Middleware::Faraday
   )
 end
+
+at_exit { LlmCostTracker.shutdown!(drain: false) if defined?(LlmCostTracker) }

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.6.0
 platform: ruby
 authors:
 - Sergii Khomenko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -283,18 +283,41 @@ 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/active_record_adapter.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/doctor/ingestion_check.rb
 - lib/llm_cost_tracker/engine.rb
 - lib/llm_cost_tracker/engine_compatibility.rb
 - lib/llm_cost_tracker/errors.rb
 - lib/llm_cost_tracker/event.rb
 - lib/llm_cost_tracker/event_metadata.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/add_ingestion_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_latency_ms_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_period_totals_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_provider_response_id_generator.rb
@@ -302,6 +325,7 @@ files:
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_usage_breakdown_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/install_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/prices_generator.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_ingestion_to_llm_cost_tracker.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_latency_ms_to_llm_api_calls.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_period_totals_to_llm_cost_tracker.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_provider_response_id_to_llm_api_calls.rb.erb
@@ -313,13 +337,17 @@ files:
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_llm_api_call_tags_to_jsonb.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_cost_precision_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_tags_to_jsonb_generator.rb
+- lib/llm_cost_tracker/inbox_event.rb
+- lib/llm_cost_tracker/ingestor_lease.rb
 - lib/llm_cost_tracker/integrations/anthropic.rb
 - lib/llm_cost_tracker/integrations/base.rb
 - lib/llm_cost_tracker/integrations/object_reader.rb
 - 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 +371,31 @@ 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_connection_cleanup.rb
+- lib/llm_cost_tracker/storage/active_record_inbox.rb
+- lib/llm_cost_tracker/storage/active_record_inbox_batch.rb
+- lib/llm_cost_tracker/storage/active_record_ingestor.rb
+- lib/llm_cost_tracker/storage/active_record_ingestor_lease.rb
+- lib/llm_cost_tracker/storage/active_record_period_totals.rb
+- lib/llm_cost_tracker/storage/active_record_periods.rb
+- lib/llm_cost_tracker/storage/active_record_rollup_batch.rb
+- lib/llm_cost_tracker/storage/active_record_rollup_upsert_sql.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 +403,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