llm_cost_tracker 0.8.0 → 0.10.0

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

@@ -72,6 +72,56 @@
   </section>
 
   <section class="lct-grid lct-two-col">
+    <section class="lct-panel">
+      <div class="lct-section-head">
+        <div>
+          <h2 class="lct-section-title">Next actions</h2>
+          <p class="lct-section-copy">Use these fixes to improve the trustworthiness of downstream cost reports.</p>
+        </div>
+      </div>
+
+      <table class="lct-table lct-table-compact">
+        <thead>
+          <tr>
+            <th>Issue</th>
+            <th>Why it matters</th>
+            <th>Suggested action</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>Unknown pricing</td>
+            <td>Cost stays <code class="lct-code">nil</code>, so totals undercount.</td>
+            <td>Update <code class="lct-code">pricing_overrides</code> or <code class="lct-code">prices_file</code>.</td>
+          </tr>
+          <tr>
+            <td>Missing tags</td>
+            <td>Attribution by tenant, user, or feature becomes less useful.</td>
+            <td>Pass <code class="lct-code">tags:</code> from middleware using request context.</td>
+          </tr>
+          <tr>
+            <td>Missing latency</td>
+            <td>Slow requests become harder to isolate on the calls page.</td>
+            <td>Make sure latency capture is enabled on every tracked request.</td>
+          </tr>
+          <% if @summary.streaming_missing_usage.positive? %>
+            <tr>
+              <td>Streams without usage</td>
+              <td>Token totals undercount when streaming responses drop the final usage event.</td>
+              <td>Send OpenAI requests with <code class="lct-code">stream_options: { include_usage: true }</code>, or wrap custom clients with <code class="lct-code">LlmCostTracker.track_stream</code>.</td>
+            </tr>
+          <% end %>
+          <% if @summary.missing_provider_response_id_count.positive? %>
+            <tr>
+              <td>Missing provider response IDs</td>
+              <td>Proof of provider-issued responses is weaker when calls cannot be tied back to provider objects.</td>
+              <td>Upgrade to the latest parser coverage and pass <code class="lct-code">provider_response_id:</code> for custom clients when the provider exposes one.</td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </section>
+
     <section class="lct-panel">
       <div class="lct-section-head">
         <div>
@@ -129,56 +179,6 @@
         </tbody>
       </table>
     </section>
-
-    <section class="lct-panel">
-      <div class="lct-section-head">
-        <div>
-          <h2 class="lct-section-title">Next actions</h2>
-          <p class="lct-section-copy">Use these fixes to improve the trustworthiness of downstream cost reports.</p>
-        </div>
-      </div>
-
-      <table class="lct-table lct-table-compact">
-        <thead>
-          <tr>
-            <th>Issue</th>
-            <th>Why it matters</th>
-            <th>Suggested action</th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr>
-            <td>Unknown pricing</td>
-            <td>Cost stays <code class="lct-code">nil</code>, so totals undercount.</td>
-            <td>Update <code class="lct-code">pricing_overrides</code> or <code class="lct-code">prices_file</code>.</td>
-          </tr>
-          <tr>
-            <td>Missing tags</td>
-            <td>Attribution by tenant, user, or feature becomes less useful.</td>
-            <td>Pass <code class="lct-code">tags:</code> from middleware using request context.</td>
-          </tr>
-          <tr>
-            <td>Missing latency</td>
-            <td>Slow requests become harder to isolate on the calls page.</td>
-            <td>Make sure latency capture is enabled on every tracked request.</td>
-          </tr>
-          <% if @summary.streaming_missing_usage.positive? %>
-            <tr>
-              <td>Streams without usage</td>
-              <td>Token totals undercount when streaming responses drop the final usage event.</td>
-              <td>Send OpenAI requests with <code class="lct-code">stream_options: { include_usage: true }</code>, or wrap custom clients with <code class="lct-code">LlmCostTracker.track_stream</code>.</td>
-            </tr>
-          <% end %>
-          <% if @summary.missing_provider_response_id_count.positive? %>
-            <tr>
-              <td>Missing provider response IDs</td>
-              <td>Proof of provider-issued responses is weaker when calls cannot be tied back to provider objects.</td>
-              <td>Upgrade to the latest parser coverage and pass <code class="lct-code">provider_response_id:</code> for custom clients when the provider exposes one.</td>
-            </tr>
-          <% end %>
-        </tbody>
-      </table>
-    </section>
   </section>
 
   <section class="lct-panel">
@@ -243,13 +243,50 @@
           </thead>
           <tbody>
             <% @service_charge_rows.each do |row| %>
+              <% unknown_cost = row.cost_status.to_s == LlmCostTracker::Billing::CostStatus::UNKNOWN %>
               <tr>
                 <td><code class="lct-code"><%= row.provider %></code></td>
                 <td><code class="lct-code"><%= row.component %></code></td>
                 <td><%= row.cost_status %></td>
                 <td class="lct-num"><%= number(row.charges_count) %></td>
                 <td class="lct-num"><%= number(row.quantity) %></td>
-                <td class="lct-num"><%= optional_money(row.total_cost) %></td>
+                <td class="lct-num<%= ' lct-num-muted' if unknown_cost %>"><%= unknown_cost ? "n/a" : money(row.total_cost) %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    </section>
+  <% end %>
+
+  <% if @streaming_health_rows.any? %>
+    <section class="lct-panel">
+      <div class="lct-section-head">
+        <div>
+          <h2 class="lct-section-title">Streaming health by provider</h2>
+          <p class="lct-section-copy">Streams without a final usage chunk land as <code class="lct-code">usage_source: unknown</code> and undercount tokens. A high unknown share for an OpenAI-compatible provider usually means <code class="lct-code">stream_options: { include_usage: true }</code> is not being injected for that host.</p>
+        </div>
+      </div>
+
+      <div class="lct-table-wrap">
+        <table class="lct-table lct-table-compact">
+          <thead>
+            <tr>
+              <th>Provider</th>
+              <th class="lct-num">Streams</th>
+              <th class="lct-num">With usage</th>
+              <th class="lct-num">Unknown</th>
+              <th class="lct-num">Unknown share</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @streaming_health_rows.each do |row| %>
+              <tr>
+                <td><code class="lct-code"><%= row.provider %></code></td>
+                <td class="lct-num"><%= number(row.streams) %></td>
+                <td class="lct-num"><%= number(row.with_usage) %></td>
+                <td class="lct-num"><%= number(row.unknown) %></td>
+                <td class="lct-num"><%= percent(row.unknown_share) %></td>
               </tr>
             <% end %>
           </tbody>
@@ -263,15 +300,16 @@
       <div class="lct-section-head">
         <div>
           <h2 class="lct-section-title">Unknown pricing by model</h2>
-          <p class="lct-section-copy">These models have token counts but no configured rates, so cost stays unknown.</p>
+          <p class="lct-section-copy">These models have token counts but no configured rates, so cost stays unknown. After the next price refresh or a <code class="lct-code">pricing_overrides</code> update, run <code class="lct-code">bin/rails llm_cost_tracker:backfill_unknown_pricing</code> to recompute these calls.</p>
         </div>
-        <%= link_to "Review calls", calls_path(current_query(sort: "unknown_pricing")), class: "lct-button lct-button-secondary" %>
+        <%= link_to "Calls", calls_path(current_query(sort: "unknown_pricing")), class: "lct-button lct-button-secondary" %>
       </div>
 
       <div class="lct-table-wrap">
         <table class="lct-table lct-table-compact">
           <thead>
             <tr>
+              <th>Provider</th>
               <th>Model</th>
               <th class="lct-num">Calls without cost</th>
               <th class="lct-num">Share of total</th>
@@ -280,6 +318,7 @@
           <tbody>
             <% @unknown_pricing_by_model.each do |row| %>
               <tr>
+                <td><code class="lct-code"><%= row.provider %></code></td>
                 <td><code class="lct-code"><%= row.model %></code></td>
                 <td class="lct-num"><%= number(row.calls) %></td>
                 <td class="lct-num"><%= percent(row.share_percent) %></td>

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