llm_cost_tracker 0.2.0.alpha2 → 0.3.0

data/lib/llm_cost_tracker/value_helpers.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module ValueHelpers
+    class << self
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), duplicated|
+            duplicated[deep_dup(key)] = deep_dup(nested_value)
+          end
+        when Array
+          value.map { |nested_value| deep_dup(nested_value) }
+        when String
+          value.dup
+        else
+          value
+        end
+      end
+
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each do |key, nested_value|
+            deep_freeze(key)
+            deep_freeze(nested_value)
+          end
+          value.frozen? ? value : value.freeze
+        when Array
+          value.each { |nested_value| deep_freeze(nested_value) }
+          value.frozen? ? value : value.freeze
+        when String
+          value.frozen? ? value : value.freeze
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmCostTracker
-  VERSION = "0.2.0.alpha2"
+  VERSION = "0.3.0"
 end

data/lib/llm_cost_tracker.rb

@@ -2,6 +2,7 @@
 
 require "active_support"
 require "active_support/notifications"
+require "monitor"
 
 require_relative "llm_cost_tracker/version"
 require_relative "llm_cost_tracker/configuration"
@@ -11,6 +12,7 @@ require_relative "llm_cost_tracker/cost"
 require_relative "llm_cost_tracker/event"
 require_relative "llm_cost_tracker/parsed_usage"
 require_relative "llm_cost_tracker/price_registry"
+require_relative "llm_cost_tracker/price_sync"
 require_relative "llm_cost_tracker/pricing"
 require_relative "llm_cost_tracker/parsers/base"
 require_relative "llm_cost_tracker/parsers/openai_usage"
@@ -18,6 +20,7 @@ require_relative "llm_cost_tracker/parsers/openai"
 require_relative "llm_cost_tracker/parsers/openai_compatible"
 require_relative "llm_cost_tracker/parsers/anthropic"
 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/budget"
@@ -28,16 +31,17 @@ require_relative "llm_cost_tracker/tag_key"
 require_relative "llm_cost_tracker/tag_query"
 require_relative "llm_cost_tracker/tag_accessors"
 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"
 
 module LlmCostTracker
-  class << self
-    attr_writer :configuration
+  CONFIGURATION_MUTEX = Monitor.new
 
+  class << self
     def configuration
-      @configuration ||= Configuration.new
+      CONFIGURATION_MUTEX.synchronize { @configuration ||= Configuration.new }
     end
 
     # Configure the gem once during application boot.
@@ -45,49 +49,67 @@ module LlmCostTracker
     # @yieldparam configuration [LlmCostTracker::Configuration]
     # @return [void]
     def configure
-      yield(configuration)
-      configuration.normalize_openai_compatible_providers!
-      warn_for_configuration!
+      config = CONFIGURATION_MUTEX.synchronize do
+        current = @configuration || Configuration.new
+        current = current.dup_for_configuration if current.finalized?
+        @configuration = current
+        yield(current)
+        current.normalize_openai_compatible_providers!
+        current.finalize!
+        current
+      end
+      warn_for_configuration!(config)
     end
 
     def reset_configuration!
-      @configuration = Configuration.new
+      CONFIGURATION_MUTEX.synchronize { @configuration = Configuration.new }
     end
 
-    # Track an LLM request manually for non-Faraday clients.
-    #
-    #   LlmCostTracker.track(
-    #     provider: :openai,
-    #     model: "gpt-4o",
-    #     input_tokens: 150,
-    #     output_tokens: 50,
-    #     feature: "chat",
-    #     user_id: current_user.id
-    #   )
-    #
-    # @param provider [String, Symbol] Provider name, such as :openai or :anthropic.
-    # @param model [String] Provider model identifier.
-    # @param input_tokens [Integer] Billed input token count.
-    # @param output_tokens [Integer] Billed output token count.
-    # @param latency_ms [Integer, nil] Optional request latency in milliseconds.
-    # @param metadata [Hash] Attribution tags and provider-specific usage metadata.
-    # @return [LlmCostTracker::Event] The tracked event.
-    def track(provider:, model:, input_tokens:, output_tokens:, latency_ms: nil, **metadata)
+    def enforce_budget!
+      Tracker.enforce_budget!
+    end
+
+    def track(provider:, model:, input_tokens:, output_tokens:, **options)
+      latency_ms = options.delete(:latency_ms)
+      stream = options.key?(:stream) ? options.delete(:stream) : false
+      usage_source = options.key?(:usage_source) ? options.delete(:usage_source) : :manual
+      enforce_budget = options.key?(:enforce_budget) ? options.delete(:enforce_budget) : false
+      metadata = options
+
+      enforce_budget! if enforce_budget
       Tracker.record(
         provider: provider.to_s,
         model: model,
         input_tokens: input_tokens,
         output_tokens: output_tokens,
         latency_ms: latency_ms,
+        stream: stream,
+        usage_source: usage_source,
+        metadata: metadata
+      )
+    end
+
+    def track_stream(provider:, model:, latency_ms: nil, enforce_budget: false, **metadata)
+      require_relative "llm_cost_tracker/stream_collector"
+      enforce_budget! if enforce_budget
+      collector = StreamCollector.new(
+        provider: provider.to_s,
+        model: model,
+        latency_ms: latency_ms,
         metadata: metadata
       )
+      yield collector
+      collector.finish!
+    rescue StandardError
+      collector&.finish!(errored: true)
+      raise
     end
 
     private
 
-    def warn_for_configuration!
-      return unless configuration.budget_exceeded_behavior == :block_requests
-      return if configuration.active_record?
+    def warn_for_configuration!(config = configuration)
+      return unless config.budget_exceeded_behavior == :block_requests
+      return if config.active_record?
 
       Logging.warn(":block_requests requires storage_backend = :active_record; preflight blocking will be skipped.")
     end

data/lib/tasks/llm_cost_tracker.rake

@@ -1,9 +1,133 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/BlockLength
 namespace :llm_cost_tracker do
   desc "Print an LLM cost report from ActiveRecord storage"
   task report: :environment do
     days = (ENV["DAYS"] || LlmCostTracker::Report::DEFAULT_DAYS).to_i
     puts LlmCostTracker::Report.generate(days: days)
   end
+
+  desc "Delete llm_api_calls older than DAYS (default: 90). Use BATCH_SIZE=N to tune."
+  task prune: :environment do
+    days = (ENV["DAYS"] || 90).to_i
+    batch_size = (ENV["BATCH_SIZE"] || LlmCostTracker::Retention::DEFAULT_BATCH_SIZE).to_i
+    deleted = LlmCostTracker::Retention.prune(older_than: days, batch_size: batch_size)
+    puts "llm_cost_tracker: pruned #{deleted} calls older than #{days} days"
+  end
+
+  namespace :prices do
+    desc(
+      "Sync built-in pricing data from LiteLLM/OpenRouter JSON sources. " \
+      "Use PREVIEW=1 to preview, STRICT=1 to fail on provider errors, " \
+      "or OUTPUT=path/to/file.json."
+    )
+    task :sync 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
+      strict = ENV["STRICT"] == "1" || ARGV.include?("--strict")
+      result = LlmCostTracker::PriceSync.sync(
+        path: output_path,
+        preview: ENV["PREVIEW"] == "1",
+        strict: strict
+      )
+
+      action = if ENV["PREVIEW"] == "1"
+                 "previewed"
+               elsif result.written
+                 "updated"
+               else
+                 "kept"
+               end
+
+      puts "llm_cost_tracker: #{action} pricing file #{result.path}"
+      print_source_usage(result.sources_used)
+      print_changes(result.changes)
+      print_discrepancies(result.discrepancies)
+      print_issues("validator rejected", result.rejected)
+      print_issues("validator flagged", result.flagged)
+      print_models("orphaned models (no JSON source match)", result.orphaned_models)
+      print_failures(result.failed_sources, heading: "source failures (kept existing values)")
+    end
+
+    desc "Compare the current pricing snapshot with LiteLLM/OpenRouter JSON sources and exit non-zero on drift."
+    task :check 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
+      result = LlmCostTracker::PriceSync.check(path: output_path)
+
+      puts "llm_cost_tracker: checked pricing file #{result.path}"
+      print_source_usage(result.sources_used)
+      print_changes(result.changes)
+      print_discrepancies(result.discrepancies)
+      print_issues("validator rejected", result.rejected)
+      print_issues("validator flagged", result.flagged)
+      print_models("orphaned models (no JSON source match)", result.orphaned_models)
+      print_failures(result.failed_sources, heading: "source failures")
+      puts "  pricing is up to date" if result.up_to_date
+      abort("llm_cost_tracker: pricing check failed") unless result.up_to_date
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength
+
+def print_source_usage(sources_used)
+  return if sources_used.empty?
+
+  puts "  sources used:"
+  sources_used.each do |source, usage|
+    version = usage.source_version ? ", version=#{usage.source_version.inspect}" : ""
+    puts "    - #{source} (#{usage.prices_count} prices#{version})"
+  end
+end
+
+def print_changes(changes)
+  puts "  changed models: #{changes.size}"
+  return if changes.empty?
+
+  changes.each do |model, fields|
+    puts "    - #{model}"
+    fields.each do |field, values|
+      puts "      #{field}: #{values['from'].inspect} -> #{values['to'].inspect}"
+    end
+  end
+end
+
+def print_discrepancies(discrepancies)
+  return if discrepancies.empty?
+
+  puts "  source discrepancies: #{discrepancies.size}"
+  discrepancies.each do |issue|
+    formatted = issue.values.map { |source, value| "#{source}=#{value.inspect}" }.join(", ")
+    puts "    - #{issue.model} #{issue.field}: #{formatted}"
+  end
+end
+
+def print_issues(heading, issues)
+  return if issues.empty?
+
+  puts "  #{heading}: #{issues.size}"
+  issues.each do |issue|
+    puts "    - #{issue.model}: #{issue.reason}"
+  end
+end
+
+def print_models(heading, models)
+  return if models.empty?
+
+  puts "  #{heading}: #{models.size}"
+  models.each { |model| puts "    - #{model}" }
+end
+
+def print_failures(failed_sources, heading:)
+  return if failed_sources.empty?
+
+  puts "  #{heading}: #{failed_sources.size}"
+  failed_sources.each do |source, message|
+    puts "    - #{source}: #{message}"
+  end
 end

data/llm_cost_tracker.gemspec

@@ -8,20 +8,21 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Sergii Khomenko"]
   spec.email         = ["sergey@mm.st"]
 
-  spec.summary       = "Self-hosted LLM API cost guardrails for Ruby and Rails"
-  spec.description   = "Tracks token usage and estimated costs for OpenAI, Anthropic, Google Gemini, " \
-                       "OpenRouter, DeepSeek, and OpenAI-compatible calls. " \
-                       "Works as Faraday middleware for Ruby clients, with ActiveRecord storage, " \
-                       "arbitrary tag-based attribution, and budget guardrails."
+  spec.summary       = "Self-hosted LLM usage and cost tracking for Ruby and Rails"
+  spec.description   = "Tracks token usage, latency, and estimated costs for OpenAI, Anthropic, " \
+                       "Google Gemini, OpenRouter, DeepSeek, and OpenAI-compatible APIs. " \
+                       "Works through Faraday middleware or explicit track/track_stream helpers, " \
+                       "with ActiveRecord storage, tag-based attribution, price sync tasks, " \
+                       "and budget guardrails."
   spec.homepage      = "https://github.com/sergey-homenko/llm_cost_tracker"
   spec.license       = "MIT"
 
   spec.required_ruby_version = ">= 3.3.0"
 
-  spec.metadata["homepage_uri"]    = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
   spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["documentation_uri"] = "#{spec.homepage}#readme"
   spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(__dir__) do
@@ -34,7 +35,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "activesupport", ">= 7.1", "< 9.0"
-  spec.add_dependency "csv", ">= 3.0"
+  spec.add_dependency "csv", "~> 3.0"
   spec.add_dependency "faraday", ">= 2.0", "< 3.0"
 
   spec.add_development_dependency "activerecord", ">= 7.1", "< 9.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm_cost_tracker
 version: !ruby/object:Gem::Version
-  version: 0.2.0.alpha2
+  version: 0.3.0
 platform: ruby
 authors:
 - Sergii Khomenko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-20 00:00:00.000000000 Z
+date: 2026-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -34,14 +34,14 @@ dependencies:
   name: csv
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
@@ -180,10 +180,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Tracks token usage and estimated costs for OpenAI, Anthropic, Google
-  Gemini, OpenRouter, DeepSeek, and OpenAI-compatible calls. Works as Faraday middleware
-  for Ruby clients, with ActiveRecord storage, arbitrary tag-based attribution, and
-  budget guardrails.
+description: Tracks token usage, latency, and estimated costs for OpenAI, Anthropic,
+  Google Gemini, OpenRouter, DeepSeek, and OpenAI-compatible APIs. Works through Faraday
+  middleware or explicit track/track_stream helpers, with ActiveRecord storage, tag-based
+  attribution, price sync tasks, and budget guardrails.
 email:
 - sergey@mm.st
 executables: []
@@ -193,20 +193,27 @@ files:
 - ".rspec"
 - CHANGELOG.md
 - LICENSE.txt
-- PLAN_0.2.md
 - README.md
 - Rakefile
+- app/assets/llm_cost_tracker/application.css
 - app/controllers/llm_cost_tracker/application_controller.rb
+- app/controllers/llm_cost_tracker/assets_controller.rb
 - app/controllers/llm_cost_tracker/calls_controller.rb
 - app/controllers/llm_cost_tracker/dashboard_controller.rb
 - app/controllers/llm_cost_tracker/data_quality_controller.rb
 - app/controllers/llm_cost_tracker/models_controller.rb
 - app/controllers/llm_cost_tracker/tags_controller.rb
 - app/helpers/llm_cost_tracker/application_helper.rb
+- app/helpers/llm_cost_tracker/chart_helper.rb
+- app/helpers/llm_cost_tracker/dashboard_filter_helper.rb
+- app/helpers/llm_cost_tracker/dashboard_filter_options_helper.rb
+- 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/filter.rb
 - app/services/llm_cost_tracker/dashboard/overview_stats.rb
 - app/services/llm_cost_tracker/dashboard/provider_breakdown.rb
+- app/services/llm_cost_tracker/dashboard/spend_anomaly.rb
 - app/services/llm_cost_tracker/dashboard/tag_breakdown.rb
 - app/services/llm_cost_tracker/dashboard/tag_key_explorer.rb
 - app/services/llm_cost_tracker/dashboard/time_series.rb
@@ -221,12 +228,17 @@ files:
 - app/views/llm_cost_tracker/errors/invalid_filter.html.erb
 - app/views/llm_cost_tracker/errors/not_found.html.erb
 - app/views/llm_cost_tracker/models/index.html.erb
+- app/views/llm_cost_tracker/shared/_active_filters.html.erb
 - app/views/llm_cost_tracker/shared/_bar.html.erb
+- app/views/llm_cost_tracker/shared/_metric_stack.html.erb
+- app/views/llm_cost_tracker/shared/_spend_chart.html.erb
+- app/views/llm_cost_tracker/shared/_tag_chips.html.erb
 - app/views/llm_cost_tracker/shared/setup_required.html.erb
 - app/views/llm_cost_tracker/tags/index.html.erb
 - app/views/llm_cost_tracker/tags/show.html.erb
 - config/routes.rb
 - lib/llm_cost_tracker.rb
+- lib/llm_cost_tracker/assets.rb
 - lib/llm_cost_tracker/budget.rb
 - lib/llm_cost_tracker/configuration.rb
 - lib/llm_cost_tracker/cost.rb
@@ -236,9 +248,11 @@ files:
 - lib/llm_cost_tracker/event.rb
 - lib/llm_cost_tracker/event_metadata.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_latency_ms_generator.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/add_streaming_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_latency_ms_to_llm_api_calls.rb.erb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_streaming_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
@@ -257,21 +271,35 @@ files:
 - lib/llm_cost_tracker/parsers/openai_compatible.rb
 - lib/llm_cost_tracker/parsers/openai_usage.rb
 - lib/llm_cost_tracker/parsers/registry.rb
+- lib/llm_cost_tracker/parsers/sse.rb
 - lib/llm_cost_tracker/period_grouping.rb
 - lib/llm_cost_tracker/price_registry.rb
+- lib/llm_cost_tracker/price_sync.rb
+- lib/llm_cost_tracker/price_sync/fetcher.rb
+- lib/llm_cost_tracker/price_sync/merger.rb
+- lib/llm_cost_tracker/price_sync/model_catalog.rb
+- lib/llm_cost_tracker/price_sync/raw_price.rb
+- lib/llm_cost_tracker/price_sync/source.rb
+- lib/llm_cost_tracker/price_sync/source_result.rb
+- lib/llm_cost_tracker/price_sync/sources/litellm.rb
+- lib/llm_cost_tracker/price_sync/sources/open_router.rb
+- lib/llm_cost_tracker/price_sync/validator.rb
 - lib/llm_cost_tracker/prices.json
 - lib/llm_cost_tracker/pricing.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/retention.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_key.rb
 - lib/llm_cost_tracker/tag_query.rb
 - lib/llm_cost_tracker/tags_column.rb
 - lib/llm_cost_tracker/tracker.rb
 - lib/llm_cost_tracker/unknown_pricing.rb
+- lib/llm_cost_tracker/value_helpers.rb
 - lib/llm_cost_tracker/version.rb
 - lib/tasks/llm_cost_tracker.rake
 - llm_cost_tracker.gemspec
@@ -279,10 +307,10 @@ homepage: https://github.com/sergey-homenko/llm_cost_tracker
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/sergey-homenko/llm_cost_tracker
-  source_code_uri: https://github.com/sergey-homenko/llm_cost_tracker
   bug_tracker_uri: https://github.com/sergey-homenko/llm_cost_tracker/issues
   changelog_uri: https://github.com/sergey-homenko/llm_cost_tracker/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/sergey-homenko/llm_cost_tracker
+  documentation_uri: https://github.com/sergey-homenko/llm_cost_tracker#readme
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -302,5 +330,5 @@ requirements: []
 rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
-summary: Self-hosted LLM API cost guardrails for Ruby and Rails
+summary: Self-hosted LLM usage and cost tracking for Ruby and Rails
 test_files: []