llm_cost_tracker 0.11.0 → 0.12.0

data/app/views/llm_cost_tracker/tags/index.html.erb

@@ -7,7 +7,7 @@
     <%= link_to "× Clear filters", tags_path(current_query(provider: nil, model: nil, page: nil)), class: "lct-filter-clear" %>
   <% end %>
 
-  <span class="lct-filter-row-meta"><%= number(@rows.size) %> tag key<%= "s" unless @rows.size == 1 %></span>
+  <span class="lct-filter-row-meta"><%= number_with_delimiter(@rows.size) %> tag key<%= "s" unless @rows.size == 1 %></span>
 </div>
 
 <% if @rows.empty? %>
@@ -30,8 +30,8 @@
         <% @rows.each do |row| %>
           <tr>
             <td><code class="lct-code-id"><%= row.key %></code></td>
-            <td class="lct-num"><%= number(row.calls_count) %></td>
-            <td class="lct-num"><%= number(row.distinct_values) %></td>
+            <td class="lct-num"><%= number_with_delimiter(row.calls_count) %></td>
+            <td class="lct-num"><%= number_with_delimiter(row.distinct_values) %></td>
             <td class="lct-num"><%= link_to "Breakdown", tag_path(row.key, current_query), class: "lct-page-link" %></td>
           </tr>
         <% end %>

data/app/views/llm_cost_tracker/tags/show.html.erb

@@ -13,7 +13,7 @@
       <%= link_to "× Clear filters", tag_path(params[:key], current_query(provider: nil, model: nil, page: nil)), class: "lct-filter-clear" %>
     <% end %>
 
-    <span class="lct-filter-row-meta"><%= number(@value_calls) %> call<%= "s" unless @value_calls == 1 %> · <%= money(@value_total_cost) %></span>
+    <span class="lct-filter-row-meta"><%= number_with_delimiter(@value_calls) %> call<%= "s" unless @value_calls == 1 %> · <%= money(@value_total_cost) %></span>
   </div>
 
   <% if @value_calls.zero? %>
@@ -26,11 +26,11 @@
       <div class="lct-stat">
         <div class="lct-stat-head"><p class="lct-stat-label">Total cost</p></div>
         <p class="lct-stat-value"><%= money(@value_total_cost) %></p>
-        <p class="lct-stat-foot">Across <%= number(@value_calls) %> calls</p>
+        <p class="lct-stat-foot">Across <%= number_with_delimiter(@value_calls) %> calls</p>
       </div>
       <div class="lct-stat">
         <div class="lct-stat-head"><p class="lct-stat-label">Calls</p></div>
-        <p class="lct-stat-value"><%= number(@value_calls) %></p>
+        <p class="lct-stat-value"><%= number_with_delimiter(@value_calls) %></p>
         <p class="lct-stat-foot">Tagged with <code class="lct-code-id"><%= @value %></code></p>
       </div>
       <div class="lct-stat">
@@ -62,7 +62,7 @@
       <%= link_to "× Clear filters", tag_path(params[:key], current_query(provider: nil, model: nil, page: nil)), class: "lct-filter-clear" %>
     <% end %>
 
-    <span class="lct-filter-row-meta"><%= number(@breakdown.tagged_calls) %> tagged call<%= "s" unless @breakdown.tagged_calls == 1 %> · <%= percent(coverage_percent(@breakdown.tagged_calls, @breakdown.total_calls)) %> coverage · <%= number(@breakdown.distinct_values) %> distinct value<%= "s" unless @breakdown.distinct_values == 1 %></span>
+    <span class="lct-filter-row-meta"><%= number_with_delimiter(@breakdown.tagged_calls) %> tagged call<%= "s" unless @breakdown.tagged_calls == 1 %> · <%= percent(coverage_percent(@breakdown.tagged_calls, @breakdown.total_calls)) %> coverage · <%= number_with_delimiter(@breakdown.distinct_values) %> distinct value<%= "s" unless @breakdown.distinct_values == 1 %></span>
   </div>
 
   <% if @breakdown.rows.empty? %>
@@ -74,23 +74,23 @@
     <div class="lct-stat-grid">
       <div class="lct-stat">
         <div class="lct-stat-head"><p class="lct-stat-label">Tagged calls</p></div>
-        <p class="lct-stat-value"><%= number(@breakdown.tagged_calls) %></p>
+        <p class="lct-stat-value"><%= number_with_delimiter(@breakdown.tagged_calls) %></p>
         <p class="lct-stat-foot">Rows that include <code class="lct-code-id"><%= params[:key] %></code></p>
       </div>
       <div class="lct-stat">
         <div class="lct-stat-head"><p class="lct-stat-label">Coverage</p></div>
         <p class="lct-stat-value"><%= percent(coverage_percent(@breakdown.tagged_calls, @breakdown.total_calls)) %></p>
-        <p class="lct-stat-foot"><%= number(@breakdown.total_calls) %> total calls in this slice</p>
+        <p class="lct-stat-foot"><%= number_with_delimiter(@breakdown.total_calls) %> total calls in this slice</p>
       </div>
       <div class="lct-stat">
         <div class="lct-stat-head"><p class="lct-stat-label">Distinct values</p></div>
-        <p class="lct-stat-value"><%= number(@breakdown.distinct_values) %></p>
+        <p class="lct-stat-value"><%= number_with_delimiter(@breakdown.distinct_values) %></p>
       </div>
     </div>
 
     <% if @breakdown.distinct_values > @breakdown.rows.size %>
       <div class="lct-alert lct-alert-info">
-        <span>Showing top <%= number(@breakdown.limit) %> values by spend.</span>
+        <span>Showing top <%= number_with_delimiter(@breakdown.limit) %> values by spend.</span>
       </div>
     <% end %>
 
@@ -101,7 +101,7 @@
             <%= sortable_header("Value", "value") %>
             <%= sortable_header("Calls", "calls", num: true) %>
             <th class="lct-num">Share</th>
-            <%= sortable_header("Total cost", "cost", num: true) %>
+            <%= sortable_header("Total cost", "cost", num: true, default: true) %>
             <%= sortable_header("Avg cost / call", "avg_cost", num: true) %>
             <th></th>
           </tr>
@@ -110,7 +110,7 @@
           <% @breakdown.rows.each do |row| %>
             <tr>
               <td><code class="lct-code-id"><%= row.value %></code></td>
-              <td class="lct-num"><%= number(row.calls) %></td>
+              <td class="lct-num"><%= number_with_delimiter(row.calls) %></td>
               <td class="lct-num"><%= percent(row.share_percent) %></td>
               <td class="lct-num"><%= money(row.total_cost) %></td>
               <td class="lct-num"><%= money(row.average_cost_per_call) %></td>

data/config/routes.rb

@@ -7,9 +7,8 @@ LlmCostTracker::Engine.routes.draw do
   resources :tags, only: %i[index show], param: :key, format: false
   get "data_quality", to: "data_quality#index", as: :data_quality
   get "pricing", to: "pricing#index", as: :pricing
-  get "reconciliation", to: "reconciliation#index", as: :reconciliation
-  post "reconciliation/import", to: "reconciliation#trigger_import", as: :reconciliation_import
 
   get "assets/#{LlmCostTracker::Assets::STYLESHEET_FILENAME}",
-      to: "assets#stylesheet", as: :stylesheet
+      to: "assets#stylesheet",
+as: :stylesheet
 end

data/lib/llm_cost_tracker/budget.rb

@@ -2,31 +2,25 @@
 
 require "bigdecimal"
 
-require_relative "logging"
 require_relative "ledger"
 require_relative "pricing/estimator"
 
 module LlmCostTracker
-  class Budget
+  module Budget
     BUDGET_TYPE_TO_PERIOD = { monthly: :month, daily: :day }.freeze
 
     class << self
-      def enforce!(provider: nil, model: nil, request: nil)
+      def enforce!(provider: nil, model: nil, request: nil, estimate: nil, force: false)
         config = LlmCostTracker.configuration
-        return unless config.budget_exceeded_behavior == :block_requests
+        return unless config.enabled
+        return unless force || config.budget_exceeded_behavior == :block_requests
 
-        estimate = estimate_cost(provider: provider, model: model, request: request)
+        estimate ||= estimate_cost(provider: provider, model: model, request: request)
         raise_per_call_pre_send(estimate, config.per_call_budget) if config.per_call_budget && estimate.positive?
 
-        budgets = { monthly: config.monthly_budget, daily: config.daily_budget }.compact
-        return if budgets.empty?
-
-        totals = totals_for(budgets.keys, time: Time.now.utc)
-
-        budgets.each do |budget_type, budget|
-          total = totals.fetch(budget_type) + estimate
-          next unless total >= budget
-
+        check_windowed({ monthly: config.monthly_budget, daily: config.daily_budget }.compact,
+                       time: Time.now.utc,
+estimate: estimate) do |budget_type, total, budget|
           raise BudgetExceededError.new(**budget_payload(
             budget_type: budget_type, total: total, budget: budget, last_event: nil, stage: :pre_send
           ))
@@ -38,13 +32,9 @@ module LlmCostTracker
         return unless event.total_cost
 
         check_per_call_budget(event, config)
-        budgets = { daily: config.daily_budget, monthly: config.monthly_budget }.compact
-        totals = totals_for(budgets.keys, time: event.tracked_at)
-
-        budgets.each do |budget_type, budget|
-          total = totals.fetch(budget_type)
-
-          handle_exceeded(budget_type: budget_type, total: total, budget: budget, last_event: event) if total >= budget
+        check_windowed({ daily: config.daily_budget, monthly: config.monthly_budget }.compact,
+                       time: event.tracked_at) do |budget_type, total, budget|
+          handle_exceeded(budget_type: budget_type, total: total, budget: budget, last_event: event)
         end
       end
 
@@ -74,14 +64,22 @@ module LlmCostTracker
         handle_exceeded(budget_type: :per_call, total: total, budget: budget, last_event: event)
       end
 
+      def check_windowed(budgets, time:, estimate: BigDecimal("0"))
+        return if budgets.empty?
+
+        totals = totals_for(budgets.keys, time: time)
+        budgets.each do |budget_type, budget|
+          total = totals.fetch(budget_type) + estimate
+          yield(budget_type, total, budget) if total >= budget
+        end
+      end
+
       def totals_for(budget_types, time:)
         return {} if budget_types.empty?
 
-        periods = budget_types.map { |type| BUDGET_TYPE_TO_PERIOD.fetch(type) }
-        period_totals = LlmCostTracker::Ledger::Period::Totals.call(periods, time: time)
-        BUDGET_TYPE_TO_PERIOD.each_with_object({}) do |(budget_type, period), totals|
-          totals[budget_type] = period_totals[period] if period_totals.key?(period)
-        end
+        period_for = budget_types.to_h { |type| [type, BUDGET_TYPE_TO_PERIOD.fetch(type)] }
+        period_totals = LlmCostTracker::Ledger::Period::Totals.call(period_for.values, time: time)
+        period_for.transform_values { |period| period_totals.fetch(period) }
       end
 
       def handle_exceeded(budget_type:, total:, budget:, last_event: nil)

data/lib/llm_cost_tracker/capture/sdk_payload.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/deep_dup"
+require "active_support/core_ext/object/try"
+
+module LlmCostTracker
+  module Capture
+    module SdkPayload
+      module_function
+
+      def normalize(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, nested), out| out[key.to_s] = normalize(nested) }
+        when Array
+          value.map { |nested| normalize(nested) }
+        when Symbol
+          value.to_s
+        when NilClass
+          nil
+        else
+          converted = container_for(value)
+          converted ? normalize(converted) : value.deep_dup
+        end
+      end
+
+      def container_for(value)
+        value.try(:deep_to_h) || value.try(:to_h)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/capture/sse.rb

@@ -7,6 +7,7 @@ module LlmCostTracker
   module Capture
     module SSE
       DONE_MARKER = "[DONE]"
+      LIMIT_BYTES = 1_048_576
 
       class << self
         def parse(body)

data/lib/llm_cost_tracker/capture/stream_collector.rb

@@ -4,8 +4,7 @@ require "active_support/core_ext/object/blank"
 require "active_support/core_ext/object/deep_dup"
 require "json"
 
-require_relative "stream"
-require_relative "../pricing/mode"
+require_relative "sse"
 require_relative "../timing"
 
 module LlmCostTracker
@@ -13,9 +12,17 @@ module LlmCostTracker
     class StreamCollector
       attr_reader :provider
 
-      def initialize(provider:, model:, latency_ms: nil, provider_response_id: nil, provider_project_id: nil,
-                     provider_api_key_id: nil, provider_workspace_id: nil, batch: nil, pricing_mode: nil,
-                     metadata: {}, context_tags: nil, request: nil)
+      def initialize(provider:,
+                     model:,
+                     latency_ms: nil,
+                     provider_response_id: nil,
+                     provider_project_id: nil,
+                     provider_api_key_id: nil,
+                     provider_workspace_id: nil,
+                     pricing_mode: nil,
+                     metadata: {},
+                     context_tags: nil,
+                     request: nil)
         @provider = provider.to_s
         @model = model
         @latency_ms = latency_ms
@@ -23,7 +30,6 @@ module LlmCostTracker
         @provider_project_id = provider_project_id
         @provider_api_key_id = provider_api_key_id
         @provider_workspace_id = provider_workspace_id
-        @batch = batch
         @pricing_mode = pricing_mode
         @metadata = (metadata || {}).deep_dup
         @context_tags = (context_tags || LlmCostTracker::Tags::Context.tags).deep_dup
@@ -38,18 +44,6 @@ module LlmCostTracker
         @mutex = Mutex.new
       end
 
-      def model
-        @mutex.synchronize { @model }
-      end
-
-      def metadata
-        @mutex.synchronize { @metadata.deep_dup }
-      end
-
-      def provider_response_id
-        @mutex.synchronize { @provider_response_id }
-      end
-
       def model=(value)
         @mutex.synchronize do
           ensure_open!
@@ -72,16 +66,20 @@ module LlmCostTracker
       end
 
       def usage(input_tokens:, output_tokens:, **extra)
+        if extra.key?(:batch)
+          raise ArgumentError,
+                "`batch:` is no longer accepted by stream.usage; " \
+                "pass `pricing_mode: :batch` to track_stream"
+        end
+
         @mutex.synchronize do
           ensure_open!
           @provider_response_id = extra.delete(:provider_response_id) || @provider_response_id
           @provider_project_id = extra.delete(:provider_project_id) || @provider_project_id
           @provider_api_key_id = extra.delete(:provider_api_key_id) || @provider_api_key_id
           @provider_workspace_id = extra.delete(:provider_workspace_id) || @provider_workspace_id
-          batch = extra.delete(:batch)
-          @batch = batch unless batch.nil?
-          @explicit_usage = TokenUsage.build(
-            **extra.slice(*TokenUsage.members),
+          @explicit_usage = Usage::TokenUsage.build(
+            **extra.slice(*Usage::TokenUsage.members),
             input_tokens: input_tokens,
             output_tokens: output_tokens
           )
@@ -110,7 +108,7 @@ module LlmCostTracker
             model: @model,
             latency_ms: @latency_ms,
             provider_response_id: @provider_response_id,
-            capture_dimensions: capture_dimensions(pricing_mode),
+            capture_dimensions: capture_dimensions,
             pricing_mode: pricing_mode,
             metadata: @metadata.deep_dup,
             context_tags: @context_tags.deep_dup,
@@ -141,13 +139,11 @@ module LlmCostTracker
         end
       end
 
-      def capture_dimensions(pricing_mode)
-        batch = @batch.nil? ? Event.batch_from_pricing_mode?(pricing_mode).presence : @batch
+      def capture_dimensions
         {
           provider_project_id: @provider_project_id.to_s.strip.presence,
           provider_api_key_id: @provider_api_key_id.to_s.strip.presence,
-          provider_workspace_id: @provider_workspace_id.to_s.strip.presence,
-          batch: batch
+          provider_workspace_id: @provider_workspace_id.to_s.strip.presence
         }.compact
       end
 
@@ -183,12 +179,8 @@ module LlmCostTracker
       end
 
       def present_model(value)
-        return nil if value.nil?
-
         string = value.to_s.presence
-        return nil if string.nil? || string == Event::UNKNOWN_MODEL
-
-        string
+        string unless string == Event::UNKNOWN_MODEL
       end
 
       def build_from_explicit_usage(snapshot)
@@ -197,7 +189,7 @@ module LlmCostTracker
           model: snapshot[:model] || Event::UNKNOWN_MODEL,
           token_usage: snapshot[:explicit_usage],
           stream: true,
-          usage_source: :manual,
+          usage_source: Usage::Source::MANUAL,
           pricing_mode: snapshot[:pricing_mode],
           **snapshot.fetch(:capture_dimensions)
         )
@@ -207,9 +199,9 @@ module LlmCostTracker
         Event.build(
           provider: @provider,
           model: snapshot[:model] || Event::UNKNOWN_MODEL,
-          token_usage: TokenUsage.build(input_tokens: 0, output_tokens: 0, total_tokens: 0),
+          token_usage: Usage::TokenUsage.build(input_tokens: 0, output_tokens: 0, total_tokens: 0),
           stream: true,
-          usage_source: :unknown,
+          usage_source: Usage::Source::UNKNOWN,
           pricing_mode: snapshot[:pricing_mode],
           **snapshot.fetch(:capture_dimensions)
         )
@@ -224,7 +216,7 @@ module LlmCostTracker
       def capture_event(data, type:)
         event = { event: type, data: strip_heavy_payload(data) }
         size = approximate_bytesize(event)
-        if @captured_bytes + size <= Capture::Stream::LIMIT_BYTES
+        if @captured_bytes + size <= Capture::SSE::LIMIT_BYTES
           @events << event
           @captured_bytes += size
         else

data/lib/llm_cost_tracker/capture/stream_tracker.rb

@@ -3,7 +3,7 @@
 require "active_support/core_ext/object/deep_dup"
 require "active_support/core_ext/object/try"
 
-require_relative "../logging"
+require_relative "sdk_payload"
 
 module LlmCostTracker
   module Capture
@@ -26,13 +26,24 @@ module LlmCostTracker
         if @stream.instance_variable_defined?(:@iterator)
           iterator = @stream.instance_variable_get(:@iterator)
           if iterator.respond_to?(:each)
-            @stream.instance_variable_set(:@iterator, Enumerator.new do |yielder|
-              each_from(iterator) { |event| yielder << event }
-            end)
+            @stream.instance_variable_set(:@iterator,
+                                          Enumerator.new do |yielder|
+                                            each_from(iterator) { |event| yielder << event }
+                                          end)
             iterator_wrapped = true
           end
         end
-        wrap_each if !iterator_wrapped && @stream.respond_to?(:each)
+        each_wrapped = false
+        if !iterator_wrapped && @stream.respond_to?(:each)
+          wrap_each
+          each_wrapped = true
+        end
+        unless iterator_wrapped || each_wrapped
+          Logging.warn(
+            "stream integration found no wrappable iterator on #{@stream.class} " \
+            "(missing both `@iterator` ivar and `#each`); usage will not be captured"
+          )
+        end
 
         register_orphan_finalizer
         @stream
@@ -75,35 +86,13 @@ module LlmCostTracker
 
       def capture(event)
         raw_payload = event.try(:deep_to_h) || event.try(:to_h) || {}
-        payload = normalize(raw_payload)
+        payload = SdkPayload.normalize(raw_payload)
         type = event.try(:type) || payload["type"]
         @collector.event(payload, type: type&.to_s)
       rescue StandardError => e
         warn_capture_failure(e)
       end
 
-      def normalize(value)
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, nested), normalized|
-            normalized[key.to_s] = normalize(nested)
-          end
-        when Array
-          value.map { |nested| normalize(nested) }
-        when Symbol
-          value.to_s
-        when NilClass
-          nil
-        else
-          converted = begin
-            value.try(:deep_to_h) || value.try(:to_h)
-          rescue StandardError
-            nil
-          end
-          converted ? normalize(converted) : value.deep_dup
-        end
-      end
-
       def warn_capture_failure(error)
         should_warn = @mutex.synchronize do
           next false if @capture_failed

data/lib/llm_cost_tracker/capture_verifier.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "check"
+require_relative "ingestion"
+
+module LlmCostTracker
+  class CaptureVerifier
+    class << self
+      def call
+        new.checks
+      end
+
+      def report(checks = call)
+        (["LLM Cost Tracker capture verification"] + checks.map do |check|
+          "[#{check.status}] #{check.name}: #{check.message}"
+        end).join("\n")
+      end
+
+      def healthy?(checks = call)
+        checks.none? { |check| check.status == :error }
+      end
+    end
+
+    def checks
+      [
+        enabled_check,
+        *integration_checks,
+        *storage_checks
+      ].compact
+    end
+
+    private
+
+    def enabled_check
+      return Check.new(:ok, "tracking", "enabled") if LlmCostTracker.configuration.enabled
+
+      Check.new(:error, "tracking", "disabled; set config.enabled = true before verifying capture")
+    end
+
+    def integration_checks
+      enabled = LlmCostTracker.configuration.instrumented_integrations
+      if enabled.empty?
+        return [
+          Check.new(:ok, "sdk integrations", "none enabled; Faraday middleware and manual capture remain available")
+        ]
+      end
+
+      LlmCostTracker::Integrations.checks.map do |check|
+        check.with(name: "sdk integration #{check.name}")
+      end
+    end
+
+    def storage_checks
+      LlmCostTracker::Ingestion.verify
+    rescue LlmCostTracker::Error => e
+      [Check.new(:error, "storage", e.message)]
+    end
+  end
+end

data/lib/llm_cost_tracker/charges/cost.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module LlmCostTracker
+  module Charges
+    Cost = Data.define(:components, :total, :currency) do
+      def self.from_h(attributes)
+        components = attributes.key?(:components) ? attributes[:components] : attributes.except(:total_cost, :currency)
+        total = attributes.fetch(:total) { attributes[:total_cost] }
+        new(
+          components: components.transform_values { |value| BigDecimal(value.to_s) }.freeze,
+          total: total && BigDecimal(total.to_s),
+          currency: attributes[:currency]
+        )
+      end
+
+      def to_h
+        {
+          components: components.transform_values { |value| value.to_s("F") },
+          total: total&.to_s("F"),
+          currency: currency
+        }
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/{billing → charges}/cost_status.rb

@@ -1,19 +1,29 @@
 # frozen_string_literal: true
 
-require_relative "components"
+require_relative "../usage/source"
 
 module LlmCostTracker
-  module Billing
+  module Charges
     module CostStatus
       COMPLETE = "complete"
       FREE = "free"
       PARTIAL = "partial"
       UNKNOWN = "unknown"
+      INCOMPLETE = [UNKNOWN, PARTIAL].freeze
+
+      def self.unknown_pricing_sql(total_cost: "total_cost", cost_status: "cost_status")
+        statuses = INCOMPLETE.map { |status| ActiveRecord::Base.connection.quote(status) }.join(", ")
+        "#{total_cost} IS NULL OR #{cost_status} IN (#{statuses})"
+      end
 
       # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-      def self.call(token_usage:, usage_source:, token_cost:, service_line_items:, total_cost:,
+      def self.call(token_usage:,
+                    usage_source:,
+                    token_cost:,
+                    service_line_items:,
+                    total_cost:,
                     token_pricing_partial: false)
-        return UNKNOWN if usage_source == :unknown
+        return UNKNOWN if usage_source == Usage::Source::UNKNOWN
 
         token_billable = token_usage.priced_quantities.any? { |_key, quantity| quantity.positive? }
         service_billable = false