llm_cost_tracker 0.4.0 → 0.5.0

data/lib/llm_cost_tracker/tag_context.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support/isolated_execution_state"
+
+require_relative "value_helpers"
+
+module LlmCostTracker
+  module TagContext
+    KEY = :llm_cost_tracker_tags
+
+    class << self
+      def with(tags)
+        stack = current_stack
+        ActiveSupport::IsolatedExecutionState[KEY] = stack + [normalize(tags)]
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState[KEY] = stack
+      end
+
+      def tags
+        config_tags.merge(scoped_tags)
+      end
+
+      def clear!
+        ActiveSupport::IsolatedExecutionState[KEY] = []
+      end
+
+      private
+
+      def config_tags
+        normalize(resolve_default_tags)
+      end
+
+      def resolve_default_tags
+        tags = LlmCostTracker.configuration.default_tags
+        tags.respond_to?(:call) ? tags.call : tags
+      end
+
+      def scoped_tags
+        current_stack.reduce({}) { |merged, tags| merged.merge(tags) }
+      end
+
+      def current_stack
+        ActiveSupport::IsolatedExecutionState[KEY] || []
+      end
+
+      def normalize(tags)
+        ValueHelpers.deep_dup(tags || {}).to_h
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/tags_column.rb

@@ -2,58 +2,96 @@
 
 module LlmCostTracker
   module TagsColumn
+    USAGE_BREAKDOWN_COLUMNS = %w[
+      cache_read_input_tokens
+      cache_write_input_tokens
+      hidden_output_tokens
+    ].freeze
+
+    USAGE_BREAKDOWN_COST_COLUMNS = %w[
+      cache_read_input_cost
+      cache_write_input_cost
+    ].freeze
+
+    def reset_column_information
+      remove_instance_variable(:@lct_schema_capabilities) if instance_variable_defined?(:@lct_schema_capabilities)
+
+      super
+    end
+
     def tags_json_column?
-      tags_jsonb_column? || tags_mysql_json_column?
+      capabilities = lct_schema_capabilities
+
+      capabilities.fetch(:tags_jsonb) || capabilities.fetch(:tags_mysql_json)
     end
 
     def tags_jsonb_column?
-      column = columns_hash["tags"]
-      return false unless column
-
-      column.type == :jsonb || column.sql_type.to_s.downcase == "jsonb"
+      lct_schema_capabilities.fetch(:tags_jsonb)
     end
 
     def tags_mysql_json_column?
-      column = columns_hash["tags"]
-      return false unless column
-      return false if tags_jsonb_column?
-
-      column.type == :json && connection.adapter_name.match?(/mysql/i)
+      lct_schema_capabilities.fetch(:tags_mysql_json)
     end
 
     def latency_column?
-      columns_hash.key?("latency_ms")
+      lct_schema_capabilities.fetch(:latency)
     end
 
     def stream_column?
-      columns_hash.key?("stream")
+      lct_schema_capabilities.fetch(:stream)
     end
 
     def usage_source_column?
-      columns_hash.key?("usage_source")
+      lct_schema_capabilities.fetch(:usage_source)
     end
 
     def provider_response_id_column?
-      columns_hash.key?("provider_response_id")
+      lct_schema_capabilities.fetch(:provider_response_id)
     end
 
     def pricing_mode_column?
-      columns_hash.key?("pricing_mode")
+      lct_schema_capabilities.fetch(:pricing_mode)
     end
 
     def usage_breakdown_columns?
-      %w[
-        cache_read_input_tokens
-        cache_write_input_tokens
-        hidden_output_tokens
-      ].all? { |column| columns_hash.key?(column) }
+      lct_schema_capabilities.fetch(:usage_breakdown)
     end
 
     def usage_breakdown_cost_columns?
-      %w[
-        cache_read_input_cost
-        cache_write_input_cost
-      ].all? { |column| columns_hash.key?(column) }
+      lct_schema_capabilities.fetch(:usage_breakdown_cost)
+    end
+
+    private
+
+    def lct_schema_capabilities
+      columns = columns_hash
+      adapter_name = connection.adapter_name
+      cache = @lct_schema_capabilities
+
+      return cache.fetch(:values) if cache && cache.fetch(:columns).equal?(columns) &&
+                                     cache.fetch(:adapter_name) == adapter_name
+
+      values = build_lct_schema_capabilities(columns, adapter_name)
+      @lct_schema_capabilities = { columns: columns, adapter_name: adapter_name, values: values }
+      values
+    end
+
+    def build_lct_schema_capabilities(columns, adapter_name)
+      tag_column = columns["tags"]
+      tags_jsonb = tag_column && (tag_column.type == :jsonb || tag_column.sql_type.to_s.downcase == "jsonb")
+      tags_mysql_json = tag_column && !tags_jsonb && tag_column.type == :json && adapter_name.match?(/mysql/i)
+
+      {
+        tags_jsonb: tags_jsonb ? true : false,
+        tags_mysql_json: tags_mysql_json ? true : false,
+        latency: columns.key?("latency_ms"),
+        stream: columns.key?("stream"),
+        usage_source: columns.key?("usage_source"),
+        provider_response_id: columns.key?("provider_response_id"),
+        pricing_mode: columns.key?("pricing_mode"),
+        usage_breakdown: USAGE_BREAKDOWN_COLUMNS.all? { |column| columns.key?(column) },
+        usage_breakdown_cost: USAGE_BREAKDOWN_COST_COLUMNS.all? { |column| columns.key?(column) }
+      }
     end
   end
 end

data/lib/llm_cost_tracker/tracker.rb

@@ -6,7 +6,7 @@ module LlmCostTracker
   class Tracker
     EVENT_NAME = "llm_request.llm_cost_tracker"
 
-    USAGE_SOURCES = %i[response stream_final manual unknown].freeze
+    USAGE_SOURCES = %i[response stream_final sdk_response manual unknown].freeze
 
     class << self
       def enforce_budget!
@@ -19,6 +19,7 @@ module LlmCostTracker
                  usage_source: nil, provider_response_id: nil, pricing_mode: nil, metadata: {})
         return unless LlmCostTracker.configuration.enabled
 
+        model = normalize_model(model)
         usage = usage_data(input_tokens, output_tokens, metadata, pricing_mode)
         cost_data = cost_for_usage(provider, model, usage)
 
@@ -68,6 +69,8 @@ module LlmCostTracker
         )
       end
 
+      def normalize_model(value) = value.to_s.strip.then { |model| model.empty? ? ParsedUsage::UNKNOWN_MODEL : model }
+
       def build_event(provider:, model:, usage:, cost_data:, metadata:, latency_ms:, stream:, usage_source:,
                       provider_response_id:)
         Event.new(
@@ -81,7 +84,7 @@ module LlmCostTracker
           hidden_output_tokens: usage[:hidden_output_tokens],
           pricing_mode: usage[:pricing_mode],
           cost: cost_data,
-          tags: LlmCostTracker.configuration.default_tags.merge(EventMetadata.tags(metadata)).freeze,
+          tags: LlmCostTracker::TagContext.tags.merge(EventMetadata.tags(metadata)).freeze,
           latency_ms: normalized_latency_ms(latency_ms),
           stream: stream ? true : false,
           usage_source: normalized_usage_source(usage_source),

data/lib/llm_cost_tracker/version.rb

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

data/lib/llm_cost_tracker.rb

@@ -25,9 +25,11 @@ require_relative "llm_cost_tracker/parsers/gemini"
 require_relative "llm_cost_tracker/parsers/sse"
 require_relative "llm_cost_tracker/parsers/registry"
 require_relative "llm_cost_tracker/middleware/faraday"
+require_relative "llm_cost_tracker/integrations/registry"
 require_relative "llm_cost_tracker/budget"
 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/tags_column"
 require_relative "llm_cost_tracker/tag_key"
 require_relative "llm_cost_tracker/tag_query"
@@ -37,6 +39,7 @@ 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"
 
 module LlmCostTracker
   CONFIGURATION_MUTEX = Monitor.new
@@ -52,10 +55,11 @@ module LlmCostTracker
         current = current.dup_for_configuration if current.finalized?
         @configuration = current
         yield(current)
-        current.normalize_openai_compatible_providers!
+        current.openai_compatible_providers = current.openai_compatible_providers.dup
         current.finalize!
         current
       end
+      Integrations.install!
       warn_for_configuration!(config)
     end
 
@@ -63,14 +67,20 @@ module LlmCostTracker
       CONFIGURATION_MUTEX.synchronize { @configuration = Configuration.new }
       UnknownPricing.reset! if defined?(UnknownPricing)
       Storage::ActiveRecordStore.reset! if defined?(Storage::ActiveRecordStore)
+      TagContext.clear! if defined?(TagContext)
     end
 
     def enforce_budget!
       Tracker.enforce_budget!
     end
 
-    def track(provider:, model:, input_tokens:, output_tokens:, latency_ms: nil, stream: false, usage_source: :manual,
-              enforce_budget: false, provider_response_id: nil, pricing_mode: nil, **metadata)
+    def with_tags(tags = nil, **kwargs, &)
+      merged = (tags || {}).to_h.merge(kwargs)
+      TagContext.with(merged, &)
+    end
+
+    def track(provider:, input_tokens:, output_tokens:, model: nil, latency_ms: nil, stream: false,
+              usage_source: :manual, enforce_budget: false, provider_response_id: nil, pricing_mode: nil, **metadata)
       enforce_budget! if enforce_budget
       Tracker.record(
         provider: provider.to_s,
@@ -86,7 +96,7 @@ module LlmCostTracker
       )
     end
 
-    def track_stream(provider:, model:, latency_ms: nil, enforce_budget: false, provider_response_id: nil,
+    def track_stream(provider:, model: nil, latency_ms: nil, enforce_budget: false, provider_response_id: nil,
                      pricing_mode: nil, **metadata)
       require_relative "llm_cost_tracker/stream_collector"
       enforce_budget! if enforce_budget

data/lib/tasks/llm_cost_tracker.rake

@@ -2,6 +2,14 @@
 
 # rubocop:disable Metrics/BlockLength
 namespace :llm_cost_tracker do
+  desc "Check LLM Cost Tracker setup"
+  task :doctor do
+    Rake::Task["environment"].invoke if Rake::Task.task_defined?("environment")
+    checks = LlmCostTracker::Doctor.call
+    puts LlmCostTracker::Doctor.report(checks)
+    abort("llm_cost_tracker: doctor found setup errors") unless LlmCostTracker::Doctor.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
@@ -18,7 +26,7 @@ namespace :llm_cost_tracker do
 
   namespace :prices do
     desc(
-      "Sync built-in pricing data from LiteLLM/OpenRouter JSON sources. " \
+      "Sync the configured pricing file from LiteLLM/OpenRouter JSON sources. " \
       "Use PREVIEW=1 to preview, STRICT=1 to fail on provider errors, " \
       "or OUTPUT=path/to/file.json."
     )
@@ -26,7 +34,7 @@ namespace :llm_cost_tracker do
       Rake::Task["environment"].invoke if Rake::Task.task_defined?("environment")
       require_relative "../llm_cost_tracker"
 
-      output_path = ENV["OUTPUT"] || LlmCostTracker.configuration.prices_file || LlmCostTracker::PriceSync::DEFAULT_OUTPUT_PATH
+      output_path = price_sync_output_path
       strict = ENV["STRICT"] == "1" || ARGV.include?("--strict")
       result = LlmCostTracker::PriceSync.sync(
         path: output_path,
@@ -57,7 +65,7 @@ namespace :llm_cost_tracker do
       Rake::Task["environment"].invoke if Rake::Task.task_defined?("environment")
       require_relative "../llm_cost_tracker"
 
-      output_path = ENV["OUTPUT"] || LlmCostTracker.configuration.prices_file || LlmCostTracker::PriceSync::DEFAULT_OUTPUT_PATH
+      output_path = price_sync_output_path
       result = LlmCostTracker::PriceSync.check(path: output_path)
 
       puts "llm_cost_tracker: checked pricing file #{result.path}"
@@ -131,3 +139,13 @@ def print_failures(failed_sources, heading:)
     puts "    - #{source}: #{message}"
   end
 end
+
+def price_sync_output_path
+  path = LlmCostTracker::PriceSync.configured_output_path
+  return path if path
+
+  abort(
+    "llm_cost_tracker: configure prices_file, run bin/rails generate llm_cost_tracker:prices, " \
+    "or set OUTPUT=config/llm_cost_tracker_prices.yml"
+  )
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm_cost_tracker
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Sergii Khomenko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-24 00:00:00.000000000 Z
+date: 2026-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -240,6 +240,7 @@ files:
 - app/helpers/llm_cost_tracker/dashboard_query_helper.rb
 - app/helpers/llm_cost_tracker/pagination_helper.rb
 - app/services/llm_cost_tracker/dashboard/data_quality.rb
+- app/services/llm_cost_tracker/dashboard/data_quality_aggregate.rb
 - app/services/llm_cost_tracker/dashboard/filter.rb
 - app/services/llm_cost_tracker/dashboard/overview_stats.rb
 - app/services/llm_cost_tracker/dashboard/provider_breakdown.rb
@@ -271,7 +272,9 @@ files:
 - lib/llm_cost_tracker/assets.rb
 - lib/llm_cost_tracker/budget.rb
 - lib/llm_cost_tracker/configuration.rb
+- lib/llm_cost_tracker/configuration/instrumentation.rb
 - lib/llm_cost_tracker/cost.rb
+- lib/llm_cost_tracker/doctor.rb
 - lib/llm_cost_tracker/engine.rb
 - lib/llm_cost_tracker/engine_compatibility.rb
 - lib/llm_cost_tracker/errors.rb
@@ -291,11 +294,15 @@ files:
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_usage_breakdown_to_llm_api_calls.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/create_llm_api_calls.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/initializer.rb.erb
-- lib/llm_cost_tracker/generators/llm_cost_tracker/templates/llm_cost_tracker_prices.yml.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_llm_api_call_cost_precision.rb.erb
 - 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/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/llm_api_call.rb
 - lib/llm_cost_tracker/logging.rb
 - lib/llm_cost_tracker/middleware/faraday.rb
@@ -311,6 +318,7 @@ files:
 - lib/llm_cost_tracker/parsers/sse.rb
 - lib/llm_cost_tracker/period_grouping.rb
 - lib/llm_cost_tracker/period_total.rb
+- lib/llm_cost_tracker/price_freshness.rb
 - lib/llm_cost_tracker/price_registry.rb
 - lib/llm_cost_tracker/price_sync.rb
 - lib/llm_cost_tracker/price_sync/fetcher.rb
@@ -331,11 +339,13 @@ files:
 - 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_rollups.rb
 - lib/llm_cost_tracker/storage/active_record_store.rb
 - lib/llm_cost_tracker/stream_collector.rb
 - lib/llm_cost_tracker/tag_accessors.rb
+- lib/llm_cost_tracker/tag_context.rb
 - lib/llm_cost_tracker/tag_key.rb
 - lib/llm_cost_tracker/tag_query.rb
 - lib/llm_cost_tracker/tags_column.rb

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/llm_cost_tracker_prices.yml.erb

@@ -1,51 +0,0 @@
-# Local LlmCostTracker price overrides.
-#
-# Add only the models you want to override or add. Built-in prices still come
-# from the gem's prices.json, and Ruby pricing_overrides still take precedence.
-#
-# Units: USD per 1M tokens.
-#
-# Supported price keys:
-# - input
-# - output
-# - cache_read_input
-# - cache_write_input
-# - mode_input / mode_output / mode_cache_read_input / mode_cache_write_input
-#
-# Optional metadata keys, ignored by cost calculation:
-# - _source
-# - _source_version
-# - _fetched_at
-# - _updated
-# - _notes
-# - _validator_override
-#
-# Example: custom fine-tune
-# models:
-#   "ft:gpt-4o-mini:my-org":
-#     input: 0.30
-#     cache_read_input: 0.15
-#     output: 1.20
-#     _notes: "Internal fine-tune rate"
-#
-# Example: alternate pricing mode
-# models:
-#   "batchable-model":
-#     input: 1.00
-#     output: 2.00
-#     batch_input: 0.50
-#     batch_output: 1.00
-#
-# Example: negotiated provider discount
-# models:
-#   "gpt-4o":
-#     input: 2.00
-#     output: 8.00
-#     _source: "manual"
-#     _updated: "2026-04-18"
-#
-# Use _source: "manual" for custom or orphaned entries you never want sync to touch.
-# Use _validator_override: ["skip_relative_change"] if a negotiated price would
-# otherwise trip the >3x sync warning.
-
-models: