llm_cost_tracker 0.8.0 → 0.9.0

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

@@ -0,0 +1,183 @@
+<section class="lct-panel">
+  <div class="lct-toolbar-head">
+    <h2 class="lct-section-title">Provider Invoice Reconciliation <span class="lct-badge lct-badge-warn">Experimental</span></h2>
+    <% if @last_imported_at %>
+      <p class="lct-state-copy">Last import: <%= @last_imported_at.utc.iso8601 %></p>
+    <% end %>
+  </div>
+  <p class="lct-state-copy">
+    Experimental in v0.9.0 — public API may change in v0.9.x based on feedback.
+    <%= link_to "Open an issue", "https://github.com/sergey-homenko/llm_cost_tracker/issues", target: "_blank", rel: "noopener" %>
+    if you use it.
+  </p>
+</section>
+
+<% if flash[:notice] %>
+  <section class="lct-panel"><p class="lct-state-copy"><%= flash[:notice] %></p></section>
+<% end %>
+<% if flash[:alert] %>
+  <section class="lct-panel"><p class="lct-state-copy"><%= flash[:alert] %></p></section>
+<% end %>
+
+<% if @configured_importers.any? %>
+  <section class="lct-panel">
+    <h3 class="lct-section-title">Trigger import</h3>
+    <% @configured_importers.each_key do |source| %>
+      <%= button_to "Re-import #{source}",
+            reconciliation_import_path(source: source),
+            method: :post,
+            class: "lct-button lct-button-secondary" %>
+    <% end %>
+  </section>
+<% end %>
+
+<% if !@reconciliation_enabled %>
+  <section class="lct-panel lct-empty">
+    <h2 class="lct-state-title">Reconciliation disabled</h2>
+    <p class="lct-state-copy">
+      Provider invoice reconciliation is opt-in because it requires admin/org-level
+      provider API keys (OpenAI <code>sk-admin-…</code>, Anthropic admin keys, GCP
+      <code>billing.viewer</code>) — separate from the runtime inference key the
+      tracker uses. Enable explicitly in the initializer:
+    </p>
+    <pre class="lct-state-pre"><code>LlmCostTracker.configure do |config|
+  config.reconciliation_enabled = true
+end</code></pre>
+  </section>
+<% elsif !@reconciliation_installed %>
+  <section class="lct-panel lct-empty">
+    <h2 class="lct-state-title">Reconciliation not installed</h2>
+    <p class="lct-state-copy">
+      Run the optional migration to create the reconciliation tables:
+    </p>
+    <pre class="lct-state-pre"><code>bin/rails generate llm_cost_tracker:reconciliation
+bin/rails db:migrate</code></pre>
+  </section>
+<% elsif @diffs.empty? %>
+  <section class="lct-panel lct-empty">
+    <h2 class="lct-state-title">No invoices imported yet</h2>
+    <p class="lct-state-copy">
+      Reconciliation compares provider-side invoices against local cost. Once you import
+      invoice rows via <code>LlmCostTracker::Reconciliation.import</code>, they appear here.
+    </p>
+  </section>
+<% else %>
+  <section class="lct-panel">
+    <h3 class="lct-section-title">Latest period per source / provider / currency</h3>
+    <table class="lct-table">
+      <thead>
+        <tr>
+          <th>Source</th>
+          <th>Provider</th>
+          <th>Currency</th>
+          <th>Period</th>
+          <th class="lct-num">Provider total</th>
+          <th class="lct-num">Local total</th>
+          <th class="lct-num">Delta</th>
+          <th class="lct-num">%</th>
+          <th>Status</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% @diffs.each do |diff| %>
+          <tr>
+            <td><%= diff.source %></td>
+            <td><%= diff.provider %></td>
+            <td><%= diff.currency %></td>
+            <td><%= diff.period_start %> → <%= diff.period_end %></td>
+            <td class="lct-num"><%= money(diff.provider_total) %></td>
+            <td class="lct-num"><%= money(diff.local_total) %></td>
+            <td class="lct-num"><%= money(diff.delta_amount) %></td>
+            <td class="lct-num"><%= diff.delta_percent.nil? ? "—" : "#{diff.delta_percent}%" %></td>
+            <td>
+              <% if diff.aligned?(threshold_percent: @threshold) %>
+                <span class="lct-badge lct-badge-ok">Aligned</span>
+              <% else %>
+                <span class="lct-badge lct-badge-warn">Drift</span>
+              <% end %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </section>
+
+  <% @diffs.each do |diff| %>
+    <% next if diff.unmatched_provider_rows.empty? && diff.unmatched_local_calls.empty? && diff.non_cost_rows.empty? %>
+
+    <section class="lct-panel">
+      <h3 class="lct-section-title"><%= diff.source %> / <%= diff.provider %> / <%= diff.currency %> — drill down</h3>
+
+      <% if diff.unmatched_provider_rows.any? %>
+        <h4 class="lct-state-title">
+          Provider rows without a matching local call
+          <% if diff.unmatched_provider_rows_truncated? %>
+            <small>(showing <%= diff.unmatched_provider_rows.size %> of <%= diff.unmatched_provider_rows_total %>, ranked by billed amount)</small>
+          <% end %>
+        </h4>
+        <table class="lct-table">
+          <thead>
+            <tr><th>External ID</th><th>Match basis</th><th>Attribution</th><th class="lct-num">Billed</th></tr>
+          </thead>
+          <tbody>
+            <% diff.unmatched_provider_rows.each do |row| %>
+              <tr>
+                <td><%= row[:external_id] %></td>
+                <td><%= row[:match_basis] %></td>
+                <td><%= attribution_summary(row[:attribution]) %></td>
+                <td class="lct-num"><%= optional_money(row[:billed_amount]) %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      <% end %>
+
+      <% if diff.unmatched_local_calls.any? %>
+        <h4 class="lct-state-title">
+          Local calls no provider invoice can explain
+          <% if diff.unmatched_local_calls_truncated? %>
+            <small>(showing <%= diff.unmatched_local_calls.size %> of <%= diff.unmatched_local_calls_total %>, ranked by total cost)</small>
+          <% end %>
+        </h4>
+        <table class="lct-table">
+          <thead>
+            <tr><th>Attribution</th><th class="lct-num">Calls</th><th class="lct-num">Total cost</th></tr>
+          </thead>
+          <tbody>
+            <% diff.unmatched_local_calls.each do |row| %>
+              <tr>
+                <td><%= attribution_summary(row[:attribution]) %></td>
+                <td class="lct-num"><%= number(row[:count]) %></td>
+                <td class="lct-num"><%= money(row[:total_cost]) %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      <% end %>
+
+      <% if diff.non_cost_rows.any? %>
+        <h4 class="lct-state-title">
+          Non-cost evidence (free quota, credits, adjustments)
+          <% if diff.non_cost_rows_truncated? %>
+            <small>(showing <%= diff.non_cost_rows.size %> of <%= diff.non_cost_rows_total %>, ranked by amount)</small>
+          <% end %>
+        </h4>
+        <table class="lct-table">
+          <thead>
+            <tr><th>Row type</th><th>Meter</th><th>Attribution</th><th class="lct-num">Amount</th></tr>
+          </thead>
+          <tbody>
+            <% diff.non_cost_rows.each do |row| %>
+              <tr>
+                <td><%= row[:row_type] %></td>
+                <td><%= row[:meter] %></td>
+                <td><%= attribution_summary(row[:attribution]) %></td>
+                <td class="lct-num"><%= optional_money(row[:billed_amount]) %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      <% end %>
+    </section>
+  <% end %>
+<% end %>

data/app/views/llm_cost_tracker/shared/_bar.html.erb

@@ -1,5 +1,5 @@
 <% variant_class = local_assigns[:variant] == "budget" ? " lct-budget-fill" : "" %>
 
 <div class="lct-bar-track" aria-hidden="true">
-  <div class="lct-bar-fill<%= variant_class %>" style="width: <%= bar_width(value, max) %>"></div>
+  <div data-lct-style="<%= inline_style("width: #{bar_width(value, max)}") %>" class="lct-bar-fill<%= variant_class %>"></div>
 </div>

data/app/views/llm_cost_tracker/shared/_filters.html.erb

@@ -10,6 +10,9 @@
 %>
 
 <form class="lct-filters" action="<%= path %>" method="get">
+  <% local_assigns.fetch(:hidden_fields, {}).each do |key, val| %>
+    <%= hidden_field_tag(key, val) %>
+  <% end %>
   <div class="lct-filter-row">
     <% if fields.include?(:from) %>
       <div class="lct-field">

data/app/views/llm_cost_tracker/shared/_metric_stack.html.erb

@@ -5,7 +5,7 @@
 <% else %>
   <div class="lct-stack-track" aria-hidden="true">
     <% visible_segments.each do |segment| %>
-      <span class="lct-stack-fill <%= segment[:css_class] %>" style="width: <%= segment[:percent].round(2) %>%"></span>
+      <span data-lct-style="<%= inline_style("width: #{segment[:percent].round(2)}%") %>" class="lct-stack-fill <%= segment[:css_class] %>"></span>
     <% end %>
   </div>
 

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

@@ -1,3 +1,61 @@
+<% if @value.present? %>
+  <section class="lct-panel lct-toolbar">
+    <div class="lct-toolbar-head">
+      <div>
+        <p class="lct-muted"><%= link_to "← All values for #{params[:key]}", tag_path(params[:key], current_query.except(:tag_value)) %></p>
+        <h2 class="lct-section-title">Tag: <code class="lct-code"><%= params[:key] %></code> = <code class="lct-code"><%= @value %></code></h2>
+      </div>
+    </div>
+
+    <%= render "llm_cost_tracker/shared/filters",
+               path: tag_path(params[:key]),
+               fields: %i[from to provider model],
+               hidden_fields: { tag_value: @value },
+               reset_path: tag_path(params[:key], tag_value: @value) %>
+  </section>
+
+  <% if @value_calls.zero? %>
+    <section class="lct-panel lct-empty">
+      <h2 class="lct-state-title">No calls tagged with <%= params[:key] %>=<%= @value %></h2>
+      <p class="lct-state-copy">No matching calls in the current slice.</p>
+      <div class="lct-state-actions">
+        <%= link_to "Back to values", tag_path(params[: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">Total cost</p>
+        <p class="lct-stat-value"><%= money(@value_total_cost) %></p>
+        <p class="lct-stat-copy">Across <%= number(@value_calls) %> calls</p>
+      </article>
+
+      <article class="lct-stat">
+        <p class="lct-stat-label">Calls</p>
+        <p class="lct-stat-value"><%= number(@value_calls) %></p>
+        <p class="lct-stat-copy">Tagged with <code class="lct-code"><%= @value %></code></p>
+      </article>
+
+      <article class="lct-stat">
+        <p class="lct-stat-label">Avg cost / call</p>
+        <p class="lct-stat-value"><%= money(@value_calls.positive? ? @value_total_cost / @value_calls : 0) %></p>
+        <p class="lct-stat-copy">Mean over the slice</p>
+      </article>
+    </section>
+
+    <section class="lct-panel">
+      <div class="lct-section-head">
+        <div>
+          <h2 class="lct-section-title">Spend over time</h2>
+          <p class="lct-section-copy">Daily total cost for calls tagged <code class="lct-code"><%= params[:key] %>=<%= @value %></code>.</p>
+        </div>
+        <%= link_to "Calls", calls_path(calls_query_for_tag(key: @key, value: @value)), class: "lct-button lct-button-secondary lct-button-compact" %>
+      </div>
+
+      <%= render "llm_cost_tracker/shared/spend_chart", series: @value_points %>
+    </section>
+  <% end %>
+<% else %>
 <section class="lct-panel lct-toolbar">
   <div class="lct-toolbar-head">
     <div>
@@ -78,6 +136,7 @@
                 <% if row.value == "(untagged)" %>
                   <span class="lct-muted">n/a</span>
                 <% else %>
+                  <%= link_to "Trend", tag_path(params[:key], current_query.merge(tag_value: row.value)), class: "lct-button lct-button-secondary lct-button-compact" %>
                   <%= link_to "Calls", calls_path(calls_query_for_tag(key: params[:key], value: row.value)), class: "lct-button lct-button-secondary lct-button-compact" %>
                 <% end %>
               </td>
@@ -88,3 +147,4 @@
     </div>
   </section>
 <% end %>
+<% end %>

data/config/routes.rb

@@ -4,9 +4,10 @@ LlmCostTracker::Engine.routes.draw do
   root "dashboard#index"
   resources :calls, only: %i[index show], constraints: { id: /\d+/ }, defaults: { format: :html }
   resources :models, only: :index
-  get "tags",      to: "tags#index",  as: :tags
-  get "tags/:key", to: "tags#show",   as: :tag, format: false
+  resources :tags, only: %i[index show], param: :key, format: false
   get "data_quality", to: "data_quality#index", as: :data_quality
+  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

data/lib/llm_cost_tracker/billing/components.rb

@@ -6,6 +6,37 @@ require_relative "../errors"
 
 module LlmCostTracker
   module Billing
+    RATE_BASES = %i[
+      per_million_tokens
+      per_million_characters
+      per_request
+      per_1k_requests
+      per_session
+      per_hour
+      per_gb_day
+      per_image
+    ].freeze
+
+    RATE_BASIS_QUANTITIES = {
+      per_million_tokens: 1_000_000,
+      per_million_characters: 1_000_000,
+      per_request: 1,
+      per_1k_requests: 1_000,
+      per_session: 1,
+      per_hour: 1,
+      per_gb_day: 1,
+      per_image: 1
+    }.freeze
+
+    DEFAULT_RATE_BASIS_BY_UNIT = {
+      token: :per_million_tokens,
+      character: :per_million_characters,
+      request: :per_request,
+      session: :per_session,
+      hour: :per_hour,
+      image: :per_image
+    }.freeze
+
     module Components
       Component = Data.define(
         :key,
@@ -16,7 +47,8 @@ module LlmCostTracker
         :unit,
         :category,
         :token_key,
-        :cost_key
+        :cost_key,
+        :rate_basis
       )
 
       REQUIRED_FIELDS = %i[key kind direction modality cache_state unit category].freeze
@@ -32,16 +64,26 @@ module LlmCostTracker
         missing = REQUIRED_FIELDS - attributes.keys
         raise Error, "components.yml entry missing #{missing.join(', ')}: #{attributes.inspect}" if missing.any?
 
+        unit = attributes.fetch(:unit).to_sym
+        rate_basis = attributes[:rate_basis]&.to_sym || Billing::DEFAULT_RATE_BASIS_BY_UNIT[unit]
+        if rate_basis.nil?
+          raise Error, "components.yml entry needs rate_basis for unit #{unit.inspect}: #{attributes.inspect}"
+        end
+        unless Billing::RATE_BASES.include?(rate_basis)
+          raise Error, "components.yml entry has unknown rate_basis #{rate_basis.inspect}: #{attributes.inspect}"
+        end
+
         Component.new(
           key: attributes.fetch(:key).to_sym,
           kind: attributes.fetch(:kind).to_sym,
           direction: attributes.fetch(:direction).to_sym,
           modality: attributes.fetch(:modality).to_sym,
           cache_state: attributes.fetch(:cache_state).to_sym,
-          unit: attributes.fetch(:unit).to_sym,
+          unit: unit,
           category: attributes.fetch(:category).to_sym,
           token_key: attributes[:token_key]&.to_sym,
-          cost_key: attributes[:cost_key]&.to_sym
+          cost_key: attributes[:cost_key]&.to_sym,
+          rate_basis: rate_basis
         )
       end
 

data/lib/llm_cost_tracker/billing/components.yml

@@ -68,6 +68,26 @@
   token_key: audio_output_tokens
   cost_key: audio_output_cost
 
+- key: image_input
+  kind: image_token
+  direction: input
+  modality: image
+  cache_state: none
+  unit: token
+  category: token
+  token_key: image_input_tokens
+  cost_key: image_input_cost
+
+- key: image_output
+  kind: image_token
+  direction: output
+  modality: image
+  cache_state: none
+  unit: token
+  category: token
+  token_key: image_output_tokens
+  cost_key: image_output_cost
+
 - key: web_search_request
   kind: web_search_request
   direction: neither
@@ -75,6 +95,34 @@
   cache_state: none
   unit: request
   category: tool
+  rate_basis: per_1k_requests
+
+- key: web_search_preview_request_reasoning
+  kind: web_search_preview_request_reasoning
+  direction: neither
+  modality: text
+  cache_state: none
+  unit: request
+  category: tool
+  rate_basis: per_1k_requests
+
+- key: web_search_preview_request_non_reasoning
+  kind: web_search_preview_request_non_reasoning
+  direction: neither
+  modality: text
+  cache_state: none
+  unit: request
+  category: tool
+  rate_basis: per_1k_requests
+
+- key: web_fetch_request
+  kind: web_fetch_request
+  direction: neither
+  modality: text
+  cache_state: none
+  unit: request
+  category: tool
+  rate_basis: per_1k_requests
 
 - key: file_search_call
   kind: file_search_call
@@ -83,6 +131,7 @@
   cache_state: none
   unit: request
   category: tool
+  rate_basis: per_1k_requests
 
 - key: container_session
   kind: container_session
@@ -91,6 +140,7 @@
   cache_state: none
   unit: session
   category: runtime
+  rate_basis: per_session
 
 - key: code_execution_request
   kind: code_execution_request
@@ -99,6 +149,7 @@
   cache_state: none
   unit: request
   category: runtime
+  rate_basis: per_1k_requests
 
 - key: code_execution_hour
   kind: code_execution_hour
@@ -107,6 +158,7 @@
   cache_state: none
   unit: hour
   category: runtime
+  rate_basis: per_hour
 
 - key: grounding_request
   kind: grounding_request
@@ -115,3 +167,22 @@
   cache_state: none
   unit: request
   category: tool
+  rate_basis: per_1k_requests
+
+- key: text_to_speech_character
+  kind: text_to_speech_character
+  direction: output
+  modality: audio
+  cache_state: none
+  unit: character
+  category: tool
+  rate_basis: per_million_characters
+
+- key: mcp_call
+  kind: mcp_call
+  direction: neither
+  modality: text
+  cache_state: none
+  unit: request
+  category: tool
+  rate_basis: per_request

data/lib/llm_cost_tracker/billing/line_item.rb

@@ -119,7 +119,7 @@ module LlmCostTracker
       def self.symbol_or_nil(value)
         return nil if value.nil?
 
-        value.is_a?(Symbol) ? value : value.to_s.to_sym
+        value.to_s.to_sym
       end
 
       def self.decimal_or_nil(value)

data/lib/llm_cost_tracker/budget.rb

@@ -19,8 +19,11 @@ module LlmCostTracker
 
         budgets.each do |budget_type, budget|
           total = totals.fetch(budget_type)
+          next unless total >= budget
 
-          handle_exceeded(budget_type: budget_type, total: total, budget: budget) if total >= budget
+          raise BudgetExceededError.new(**budget_payload(
+            budget_type: budget_type, total: total, budget: budget, last_event: nil
+          ))
         end
       end
 
@@ -87,7 +90,6 @@ module LlmCostTracker
 
       def notify_exceeded?(config, budget_type:, total:, budget:, last_event:)
         return false unless config.on_budget_exceeded
-        return true unless config.budget_exceeded_behavior == :notify
         return true unless last_event&.total_cost
         return true if budget_type == :per_call