llm_cost_tracker 0.2.0.alpha2 → 0.3.0

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

@@ -1,19 +1,63 @@
+<section class="lct-panel lct-toolbar">
+  <div class="lct-toolbar-head">
+    <h2 class="lct-section-title">Tag keys</h2>
+  </div>
+
+  <form class="lct-filters" action="<%= tags_path %>" method="get">
+    <div class="lct-filter-row lct-filter-row-basic">
+      <div class="lct-field">
+        <label for="lct-tags-from">From</label>
+        <input id="lct-tags-from" data-lct-filter-input type="date" name="from" value="<%= params[:from] %>">
+      </div>
+
+      <div class="lct-field">
+        <label for="lct-tags-to">To</label>
+        <input id="lct-tags-to" type="date" name="to" value="<%= params[:to] %>">
+      </div>
+
+      <div class="lct-field">
+        <label for="lct-tags-provider">Provider</label>
+        <%= select_tag :provider,
+                       options_for_select(provider_filter_options, params[:provider]),
+                       include_blank: "All providers",
+                       id: "lct-tags-provider" %>
+      </div>
+
+      <div class="lct-field">
+        <label for="lct-tags-model">Model</label>
+        <%= select_tag :model,
+                       options_for_select(model_filter_options, params[:model]),
+                       include_blank: "All models",
+                       id: "lct-tags-model" %>
+      </div>
+
+      <div class="lct-filter-actions">
+        <button class="lct-button" type="submit">Apply</button>
+        <%= link_to("Reset", tags_path, class: "lct-button lct-button-secondary") if any_filter_applied? %>
+      </div>
+    </div>
+  </form>
+
+  <%= render "llm_cost_tracker/shared/active_filters", chips: active_tag_filters, clear_path: tags_path %>
+</section>
+
 <% if @rows.empty? %>
   <section class="lct-panel lct-empty">
-    <h2 class="lct-section-title">No tag keys found</h2>
-    <p class="lct-muted">No calls with tags have been recorded yet. Tag keys will appear here once data is available.</p>
+    <h2 class="lct-state-title">No tag keys found</h2>
+    <p class="lct-state-copy">Tag keys will appear here once tagged calls exist in the current slice.</p>
+    <div class="lct-state-actions">
+      <%= link_to "Clear filters", tags_path, class: "lct-button lct-button-secondary" %>
+    </div>
   </section>
 <% else %>
   <section class="lct-panel">
-    <h2 class="lct-section-title">Tag Keys</h2>
-    <p class="lct-muted">All tag keys present in the dataset. Click a key to explore spend and call distribution by value.</p>
     <div class="lct-table-wrap">
-      <table class="lct-table">
+      <table class="lct-table lct-table-compact">
         <thead>
           <tr>
-            <th>Tag Key</th>
-            <th>Calls with this key</th>
-            <th>Distinct values</th>
+            <th>Tag key</th>
+            <th class="lct-num">Calls with this key</th>
+            <th class="lct-num">Distinct values</th>
             <th></th>
           </tr>
         </thead>
@@ -21,9 +65,9 @@
           <% @rows.each do |row| %>
             <tr>
               <td><code class="lct-code"><%= row.key %></code></td>
-              <td><%= number(row.calls_count) %></td>
-              <td><%= number(row.distinct_values) %></td>
-              <td><%= link_to "Breakdown →", tag_path(row.key), class: "lct-button lct-button-secondary" %></td>
+              <td class="lct-num"><%= number(row.calls_count) %></td>
+              <td class="lct-num"><%= number(row.distinct_values) %></td>
+              <td><%= link_to "Breakdown", tag_path(row.key, current_query), class: "lct-button lct-button-secondary lct-button-compact" %></td>
             </tr>
           <% end %>
         </tbody>
@@ -31,4 +75,3 @@
     </div>
   </section>
 <% end %>
-

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

@@ -1,65 +1,114 @@
-<section class="lct-panel">
-  <p class="lct-muted"><%= link_to "← All tag keys", tags_path %></p>
-  <h2 class="lct-section-title">Tag key: <code class="lct-code"><%= @tag_key %></code></h2>
-  <% if @total_calls.positive? %>
-    <p class="lct-muted">
-      <%= number(@tagged_calls) %> of <%= number(@total_calls) %> calls have this key
-      (<%= percent(coverage_percent(@tagged_calls, @total_calls)) %> coverage) &middot;
-      <%= number(@distinct_values) %> distinct <%= @distinct_values == 1 ? "value" : "values" %>
-    </p>
-  <% end %>
-  <form class="lct-filters" action="<%= tag_path(@tag_key) %>" method="get">
-    <div class="lct-field">
-      <label for="lct-from">From</label>
-      <input id="lct-from" type="date" name="from" value="<%= params[:from] %>">
-    </div>
+<% share_base = @tagged_calls.positive? ? @tagged_calls.to_f : 1.0 %>
 
-    <div class="lct-field">
-      <label for="lct-to">To</label>
-      <input id="lct-to" type="date" name="to" value="<%= params[:to] %>">
+<section class="lct-panel lct-toolbar">
+  <div class="lct-toolbar-head">
+    <div>
+      <p class="lct-muted"><%= link_to "← All tag keys", tags_path(current_query) %></p>
+      <h2 class="lct-section-title">Tag: <code class="lct-code"><%= @tag_key %></code></h2>
     </div>
+  </div>
 
-    <div class="lct-field">
-      <label for="lct-provider">Provider</label>
-      <input id="lct-provider" type="text" name="provider" value="<%= params[:provider] %>">
-    </div>
+  <form class="lct-filters" action="<%= tag_path(@tag_key) %>" method="get">
+    <div class="lct-filter-row lct-filter-row-basic">
+      <div class="lct-field">
+        <label for="lct-tag-show-from">From</label>
+        <input id="lct-tag-show-from" data-lct-filter-input type="date" name="from" value="<%= params[:from] %>">
+      </div>
 
-    <div class="lct-field">
-      <label for="lct-model">Model</label>
-      <input id="lct-model" type="text" name="model" value="<%= params[:model] %>">
-    </div>
+      <div class="lct-field">
+        <label for="lct-tag-show-to">To</label>
+        <input id="lct-tag-show-to" type="date" name="to" value="<%= params[:to] %>">
+      </div>
+
+      <div class="lct-field">
+        <label for="lct-tag-show-provider">Provider</label>
+        <%= select_tag :provider,
+                       options_for_select(provider_filter_options, params[:provider]),
+                       include_blank: "All providers",
+                       id: "lct-tag-show-provider" %>
+      </div>
+
+      <div class="lct-field">
+        <label for="lct-tag-show-model">Model</label>
+        <%= select_tag :model,
+                       options_for_select(model_filter_options, params[:model]),
+                       include_blank: "All models",
+                       id: "lct-tag-show-model" %>
+      </div>
 
-    <div class="lct-button-row">
-      <button class="lct-button" type="submit">Apply</button>
-      <%= link_to "Reset", tag_path(@tag_key), class: "lct-button lct-button-secondary" %>
+      <div class="lct-filter-actions">
+        <button class="lct-button" type="submit">Apply</button>
+        <%= link_to("Reset", tag_path(@tag_key), class: "lct-button lct-button-secondary") if any_filter_applied? %>
+      </div>
     </div>
   </form>
+
+  <%= render "llm_cost_tracker/shared/active_filters", chips: active_tag_filters, clear_path: tag_path(@tag_key) %>
+
+  <p class="lct-summary-row">
+    <span><strong><%= number(@tagged_calls) %></strong> tagged calls</span>
+    <span><strong><%= percent(coverage_percent(@tagged_calls, @total_calls)) %></strong> coverage</span>
+    <span><strong><%= number(@distinct_values) %></strong> distinct values</span>
+  </p>
 </section>
 
 <% if @rows.empty? %>
   <section class="lct-panel lct-empty">
-    <h2 class="lct-section-title">No calls tagged with <%= @tag_key %></h2>
-    <p class="lct-muted">Calls carrying this tag will appear here when they match the current filters.</p>
+    <h2 class="lct-state-title">No calls tagged with <%= @tag_key %></h2>
+    <p class="lct-state-copy">Values for this key will appear here once matching calls carry the tag in the current slice.</p>
+    <div class="lct-state-actions">
+      <%= link_to "Clear filters", tag_path(@tag_key), class: "lct-button lct-button-secondary" %>
+    </div>
   </section>
 <% else %>
+  <section class="lct-stat-grid lct-stat-grid-spaced">
+    <article class="lct-stat">
+      <p class="lct-stat-label">Tagged calls</p>
+      <p class="lct-stat-value"><%= number(@tagged_calls) %></p>
+      <p class="lct-stat-copy">Rows that include <code class="lct-code"><%= @tag_key %></code></p>
+    </article>
+
+    <article class="lct-stat">
+      <p class="lct-stat-label">Coverage</p>
+      <p class="lct-stat-value"><%= percent(coverage_percent(@tagged_calls, @total_calls)) %></p>
+      <p class="lct-stat-copy"><%= number(@total_calls) %> total calls in this slice</p>
+    </article>
+
+    <article class="lct-stat">
+      <p class="lct-stat-label">Distinct values</p>
+      <p class="lct-stat-value"><%= number(@distinct_values) %></p>
+      <p class="lct-stat-copy">Unique values currently visible</p>
+    </article>
+  </section>
+
   <section class="lct-panel">
     <div class="lct-table-wrap">
-      <table class="lct-table">
+      <table class="lct-table lct-table-compact">
         <thead>
           <tr>
             <th>Value</th>
-            <th>Calls</th>
-            <th>Total cost</th>
-            <th>Avg cost / call</th>
+            <th class="lct-num">Calls</th>
+            <th class="lct-num">Share</th>
+            <th class="lct-num">Total cost</th>
+            <th class="lct-num">Avg cost / call</th>
+            <th></th>
           </tr>
         </thead>
         <tbody>
           <% @rows.each do |row| %>
             <tr>
-              <td><%= row.value %></td>
-              <td><%= number(row.calls) %></td>
-              <td><%= money(row.total_cost) %></td>
-              <td><%= money(row.average_cost_per_call) %></td>
+              <td><code class="lct-code"><%= row.value %></code></td>
+              <td class="lct-num"><%= number(row.calls) %></td>
+              <td class="lct-num"><%= percent((row.calls / share_base) * 100.0) %></td>
+              <td class="lct-num"><%= money(row.total_cost) %></td>
+              <td class="lct-num"><%= money(row.average_cost_per_call) %></td>
+              <td>
+                <% if row.value == "(untagged)" %>
+                  <span class="lct-muted">n/a</span>
+                <% else %>
+                  <%= link_to "Calls", calls_path(calls_query_for_tag(key: @tag_key, value: row.value)), class: "lct-button lct-button-secondary lct-button-compact" %>
+                <% end %>
+              </td>
             </tr>
           <% end %>
         </tbody>

data/config/routes.rb

@@ -7,4 +7,7 @@ LlmCostTracker::Engine.routes.draw do
   get "tags",      to: "tags#index",  as: :tags
   get "tags/:key", to: "tags#show",   as: :tag, format: false
   get "data_quality", to: "data_quality#index", as: :data_quality
+
+  get "assets/#{LlmCostTracker::Assets.stylesheet_filename}",
+      to: "assets#stylesheet", as: :stylesheet
 end

data/lib/llm_cost_tracker/assets.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module LlmCostTracker
+  module Assets
+    ROOT = File.expand_path("../../app/assets/llm_cost_tracker", __dir__)
+    STYLESHEET = "application.css"
+    STYLESHEET_PATH = File.join(ROOT, STYLESHEET).freeze
+    STYLESHEET_FINGERPRINT = Digest::SHA256.file(STYLESHEET_PATH).hexdigest[0, 12].freeze
+    STYLESHEET_FILENAME = "application-#{STYLESHEET_FINGERPRINT}.css".freeze
+
+    class << self
+      def root = ROOT
+      def stylesheet_fingerprint = STYLESHEET_FINGERPRINT
+      def stylesheet_filename = STYLESHEET_FILENAME
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "value_helpers"
 
 module LlmCostTracker
   class Configuration
@@ -14,22 +15,32 @@ module LlmCostTracker
     STORAGE_ERROR_BEHAVIORS = %i[ignore warn raise].freeze
     STORAGE_BACKENDS = %i[log active_record custom].freeze
     UNKNOWN_PRICING_BEHAVIORS = %i[ignore warn raise].freeze
+    SHARED_SCALAR_ATTRIBUTES = %i[
+      enabled
+      custom_storage
+      on_budget_exceeded
+      monthly_budget
+      log_level
+      prices_file
+    ].freeze
+    SHARED_ENUM_ATTRIBUTES = {
+      storage_backend: [STORAGE_BACKENDS, :log],
+      budget_exceeded_behavior: [BUDGET_EXCEEDED_BEHAVIORS, :notify],
+      storage_error_behavior: [STORAGE_ERROR_BEHAVIORS, :warn],
+      unknown_pricing_behavior: [UNKNOWN_PRICING_BEHAVIORS, :warn]
+    }.freeze
 
-    attr_accessor :enabled,
-                  :custom_storage,     # callable object for :custom backend
-                  :default_tags,       # Hash of default tags added to every event
-                  :on_budget_exceeded, # callable, receives event hash
-                  :monthly_budget,     # Float, in USD — nil means no limit
-                  :log_level,          # :debug, :info, :warn
-                  :prices_file,        # JSON/YAML file that overrides built-in prices
-                  :pricing_overrides,  # Hash to override built-in pricing
-                  :report_tag_breakdowns # Array of tag keys to break down in the rake report
-
-    attr_reader :budget_exceeded_behavior, # :notify, :raise, :block_requests
-                :storage_backend, # :log, :active_record, :custom
-                :storage_error_behavior, # :ignore, :warn, :raise
-                :unknown_pricing_behavior, # :ignore, :warn, :raise
-                :openai_compatible_providers
+    attr_reader(
+      *SHARED_SCALAR_ATTRIBUTES,
+      :budget_exceeded_behavior,
+      :default_tags,
+      :pricing_overrides,
+      :report_tag_breakdowns,
+      :storage_backend,
+      :storage_error_behavior,
+      :unknown_pricing_behavior,
+      :openai_compatible_providers
+    )
 
     def initialize
       @enabled = true
@@ -46,55 +57,74 @@ module LlmCostTracker
       @pricing_overrides  = {}
       @report_tag_breakdowns = []
       self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
+      @finalized = false
+    end
+
+    def default_tags=(value)
+      ensure_shared_configuration_mutable!
+      @default_tags = value
     end
 
     def openai_compatible_providers=(providers)
+      ensure_shared_configuration_mutable!
       @openai_compatible_providers = normalize_openai_compatible_providers(providers)
     end
 
-    def storage_backend=(value)
-      @storage_backend = normalize_enum(:storage_backend, value, STORAGE_BACKENDS, default: :log)
+    def pricing_overrides=(value)
+      ensure_shared_configuration_mutable!
+      @pricing_overrides = value
     end
 
-    def budget_exceeded_behavior=(value)
-      @budget_exceeded_behavior = normalize_enum(
-        :budget_exceeded_behavior,
-        value,
-        BUDGET_EXCEEDED_BEHAVIORS,
-        default: :notify
-      )
+    def report_tag_breakdowns=(value)
+      ensure_shared_configuration_mutable!
+      @report_tag_breakdowns = value
     end
 
-    def storage_error_behavior=(value)
-      @storage_error_behavior = normalize_enum(
-        :storage_error_behavior,
-        value,
-        STORAGE_ERROR_BEHAVIORS,
-        default: :warn
-      )
+    SHARED_SCALAR_ATTRIBUTES.each do |name|
+      define_method("#{name}=") do |value|
+        ensure_shared_configuration_mutable!
+        instance_variable_set(:"@#{name}", value)
+      end
     end
 
-    def unknown_pricing_behavior=(value)
-      @unknown_pricing_behavior = normalize_enum(
-        :unknown_pricing_behavior,
-        value,
-        UNKNOWN_PRICING_BEHAVIORS,
-        default: :warn
-      )
+    SHARED_ENUM_ATTRIBUTES.each do |name, (allowed, default)|
+      define_method("#{name}=") do |value|
+        ensure_shared_configuration_mutable!
+        instance_variable_set(:"@#{name}", normalize_enum(name, value, allowed, default: default))
+      end
     end
 
     def normalize_openai_compatible_providers!
       self.openai_compatible_providers = openai_compatible_providers
     end
 
-    def active_record?
-      storage_backend == :active_record
+    def finalize!
+      @default_tags = ValueHelpers.deep_freeze(@default_tags || {})
+      @pricing_overrides = ValueHelpers.deep_freeze(@pricing_overrides || {})
+      @report_tag_breakdowns = ValueHelpers.deep_freeze(Array(@report_tag_breakdowns))
+      @openai_compatible_providers = ValueHelpers.deep_freeze(@openai_compatible_providers || {})
+      @finalized = true
+      self
     end
 
-    def log?
-      storage_backend == :log
+    def finalized? = @finalized
+
+    def dup_for_configuration
+      copy = dup
+      copy.instance_variable_set(:@default_tags, ValueHelpers.deep_dup(@default_tags || {}))
+      copy.instance_variable_set(:@pricing_overrides, ValueHelpers.deep_dup(@pricing_overrides || {}))
+      copy.instance_variable_set(:@report_tag_breakdowns, ValueHelpers.deep_dup(@report_tag_breakdowns || []))
+      copy.instance_variable_set(
+        :@openai_compatible_providers,
+        ValueHelpers.deep_dup(@openai_compatible_providers || {})
+      )
+      copy.instance_variable_set(:@finalized, false)
+      copy
     end
 
+    def active_record? = storage_backend == :active_record
+    def log? = storage_backend == :log
+
     private
 
     def normalize_enum(name, value, allowed, default:)
@@ -110,5 +140,11 @@ module LlmCostTracker
         normalized[host.to_s.downcase] = provider.to_s
       end
     end
+
+    def ensure_shared_configuration_mutable!
+      return unless finalized?
+
+      raise FrozenError, "can't modify frozen LlmCostTracker::Configuration"
+    end
   end
 end

data/lib/llm_cost_tracker/engine.rb

@@ -3,6 +3,8 @@
 require "rails"
 require_relative "../llm_cost_tracker"
 require_relative "engine_compatibility"
+require_relative "assets"
+require "rack/files"
 
 LlmCostTracker::EngineCompatibility.check_rails_version!(Rails.version)
 

data/lib/llm_cost_tracker/event.rb

@@ -10,6 +10,8 @@ module LlmCostTracker
     :cost,
     :tags,
     :latency_ms,
+    :stream,
+    :usage_source,
     :tracked_at
   ) do
     def to_h

data/lib/llm_cost_tracker/generators/llm_cost_tracker/add_streaming_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LlmCostTracker
+  module Generators
+    class AddStreamingGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration to add llm_api_calls.stream and llm_api_calls.usage_source"
+
+      def create_migration_file
+        migration_template(
+          "add_streaming_to_llm_api_calls.rb.erb",
+          "db/migrate/add_streaming_to_llm_api_calls.rb"
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_streaming_to_llm_api_calls.rb.erb

@@ -0,0 +1,25 @@
+class AddStreamingToLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
+  def up
+    unless column_exists?(:llm_api_calls, :stream)
+      add_column :llm_api_calls, :stream, :boolean, null: false, default: false
+      add_index  :llm_api_calls, :stream
+    end
+
+    unless column_exists?(:llm_api_calls, :usage_source)
+      add_column :llm_api_calls, :usage_source, :string
+      add_index  :llm_api_calls, :usage_source
+    end
+  end
+
+  def down
+    if column_exists?(:llm_api_calls, :usage_source)
+      remove_index  :llm_api_calls, :usage_source if index_exists?(:llm_api_calls, :usage_source)
+      remove_column :llm_api_calls, :usage_source
+    end
+
+    if column_exists?(:llm_api_calls, :stream)
+      remove_index  :llm_api_calls, :stream if index_exists?(:llm_api_calls, :stream)
+      remove_column :llm_api_calls, :stream
+    end
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/create_llm_api_calls.rb.erb

@@ -10,6 +10,8 @@ class CreateLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
       t.decimal :output_cost,   precision: 20, scale: 8
       t.decimal :total_cost,    precision: 20, scale: 8
       t.integer :latency_ms
+      t.boolean :stream,        null: false, default: false
+      t.string  :usage_source
       if postgresql?
         t.jsonb :tags, null: false, default: {}
       else
@@ -24,6 +26,8 @@ class CreateLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
     add_index :llm_api_calls, :model
     add_index :llm_api_calls, :tracked_at
     add_index :llm_api_calls, [:provider, :tracked_at]
+    add_index :llm_api_calls, :stream
+    add_index :llm_api_calls, :usage_source
     add_index :llm_api_calls, :tags, using: :gin if postgresql?
   end
 

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

@@ -14,8 +14,11 @@
 #
 # Optional metadata keys, ignored by cost calculation:
 # - _source
+# - _source_version
+# - _fetched_at
 # - _updated
 # - _notes
+# - _validator_override
 #
 # Example: custom fine-tune
 # models:
@@ -30,7 +33,11 @@
 #   "gpt-4o":
 #     input: 2.00
 #     output: 8.00
-#     _source: "Enterprise agreement"
+#     _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:

data/lib/llm_cost_tracker/llm_api_call.rb

@@ -21,6 +21,14 @@ module LlmCostTracker
     scope :without_cost, -> { where(total_cost: nil) }
     scope :unknown_pricing, -> { without_cost }
     scope :with_latency, -> { latency_column? ? where.not(latency_ms: nil) : none }
+    scope :streaming,     -> { stream_column? ? where(stream: true) : none }
+    scope :non_streaming, -> { stream_column? ? where(stream: [false, nil]) : all }
+    scope :by_usage_source, ->(source) { usage_source_column? ? where(usage_source: source.to_s) : none }
+    scope :streaming_missing_usage, lambda {
+      return none unless stream_column? && usage_source_column?
+
+      where(stream: true).where(usage_source: ["unknown", nil])
+    }
 
     scope :with_json_tags, lambda {
       if tags_json_column?
@@ -100,7 +108,7 @@ module LlmCostTracker
 
       case connection.adapter_name
       when /postgres/i
-        json_column = tags_json_column? ? column : "(#{column})::jsonb"
+        json_column = tags_jsonb_column? ? column : "(#{column})::jsonb"
         "#{json_column}->>#{connection.quote(key)}"
       when /mysql/i
         "JSON_UNQUOTE(JSON_EXTRACT(#{column}, #{connection.quote(json_path(key))}))"