llm_cost_tracker 0.7.3 → 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

@@ -0,0 +1,66 @@
+<%
+  fields = local_assigns.fetch(:fields, %i[from to provider model stream])
+  default_range = LlmCostTracker::Dashboard::DateRange.call(params: params)
+  defaults = {
+    from: default_range.from.iso8601,
+    to: default_range.to.iso8601
+  }.merge(local_assigns.fetch(:defaults, {}))
+  reset_path = local_assigns.fetch(:reset_path, path)
+  filter_scope = local_assigns.fetch(:filter_scope, params)
+%>
+
+<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">
+        <label for="lct-filter-from">From</label>
+        <input id="lct-filter-from" type="date" name="from" value="<%= params[:from] || defaults[:from] %>">
+      </div>
+    <% end %>
+
+    <% if fields.include?(:to) %>
+      <div class="lct-field">
+        <label for="lct-filter-to">To</label>
+        <input id="lct-filter-to" type="date" name="to" value="<%= params[:to] || defaults[:to] %>">
+      </div>
+    <% end %>
+
+    <% if fields.include?(:provider) %>
+      <div class="lct-field">
+        <label for="lct-filter-provider">Provider</label>
+        <%= select_tag :provider,
+                       options_for_select(provider_filter_options(filter_params: filter_scope), params[:provider]),
+                       include_blank: "All providers",
+                       id: "lct-filter-provider" %>
+      </div>
+    <% end %>
+
+    <% if fields.include?(:model) %>
+      <div class="lct-field">
+        <label for="lct-filter-model">Model</label>
+        <%= select_tag :model,
+                       options_for_select(model_filter_options(filter_params: filter_scope), params[:model]),
+                       include_blank: "All models",
+                       id: "lct-filter-model" %>
+      </div>
+    <% end %>
+
+    <% if fields.include?(:stream) %>
+      <div class="lct-field">
+        <label for="lct-filter-stream">Stream</label>
+        <%= select_tag :stream,
+                       options_for_select(LlmCostTracker::DashboardFilterHelper::STREAM_FILTER_OPTIONS, params[:stream]),
+                       include_blank: "All calls",
+                       id: "lct-filter-stream" %>
+      </div>
+    <% end %>
+
+    <div class="lct-filter-actions">
+      <button class="lct-button" type="submit">Apply</button>
+      <%= link_to("Reset", reset_path, class: "lct-button lct-button-secondary") if any_filter_applied? %>
+    </div>
+  </div>
+</form>

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/shared/_sort.html.erb

@@ -0,0 +1,13 @@
+<%
+  current = local_assigns.fetch(:current).to_s
+  options = local_assigns.fetch(:options)
+%>
+
+<nav class="lct-sort" aria-label="Sort by">
+  <% options.each do |label, value| %>
+    <%= link_to label,
+                path_for_sort.call(value),
+                class: ["lct-sort-option", ("is-active" if current == value.to_s)].compact.join(" "),
+                aria: ({ current: "true" } if current == value.to_s) %>
+  <% end %>
+</nav>

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

@@ -1,7 +1,7 @@
 <section class="lct-panel lct-empty">
   <h2 class="lct-state-title">Setup required</h2>
   <p class="lct-state-copy">
-    <%= @setup_message || "The llm_api_calls table is not available yet." %>
+    <%= @setup_message || "The llm_cost_tracker_calls table is not available yet." %>
     <% if @setup_details.present? %>
       Run <span class="lct-code">bin/rails llm_cost_tracker:doctor</span>, apply the listed migrations, and migrate your database.
     <% else %>

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

@@ -3,40 +3,9 @@
     <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" 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/filters",
+             path: tags_path,
+             fields: %i[from to provider model] %>
 
   <%= render "llm_cost_tracker/shared/active_filters", chips: active_tag_filters, clear_path: tags_path %>
 </section>

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

@@ -1,47 +1,73 @@
-<% share_base = @breakdown.tagged_calls.positive? ? @breakdown.tagged_calls.to_f : 1.0 %>
-
-<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"><%= params[:key] %></code></h2>
+<% 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>
-  </div>
 
-  <form class="lct-filters" action="<%= tag_path(params[: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" type="date" name="from" value="<%= params[:from] %>">
-      </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>
 
-      <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] %>">
+  <% 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>
 
-      <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>
+      <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>
 
-      <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>
+      <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>
 
-      <div class="lct-filter-actions">
-        <button class="lct-button" type="submit">Apply</button>
-        <%= link_to("Reset", tag_path(params[:key]), class: "lct-button lct-button-secondary") if any_filter_applied? %>
+    <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>
+      <p class="lct-muted"><%= link_to "← All tag keys", tags_path(current_query) %></p>
+      <h2 class="lct-section-title">Tag: <code class="lct-code"><%= params[:key] %></code></h2>
     </div>
-  </form>
+  </div>
+
+  <%= render "llm_cost_tracker/shared/filters",
+             path: tag_path(params[:key]),
+             fields: %i[from to provider model],
+             reset_path: tag_path(params[:key]) %>
 
   <%= render "llm_cost_tracker/shared/active_filters", chips: active_tag_filters, clear_path: tag_path(params[:key]) %>
 
@@ -103,13 +129,14 @@
             <tr>
               <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"><%= 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>
               <td>
                 <% 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>
@@ -120,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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "psych"
+
+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,
+        :kind,
+        :direction,
+        :modality,
+        :cache_state,
+        :unit,
+        :category,
+        :token_key,
+        :cost_key,
+        :rate_basis
+      )
+
+      REQUIRED_FIELDS = %i[key kind direction modality cache_state unit category].freeze
+      DEFINITIONS_PATH = File.expand_path("components.yml", __dir__)
+
+      def self.load_registry
+        Psych.safe_load_file(DEFINITIONS_PATH, permitted_classes: [], symbolize_names: true)
+             .map { |attributes| build(attributes) }
+             .freeze
+      end
+
+      def self.build(attributes)
+        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: unit,
+          category: attributes.fetch(:category).to_sym,
+          token_key: attributes[:token_key]&.to_sym,
+          cost_key: attributes[:cost_key]&.to_sym,
+          rate_basis: rate_basis
+        )
+      end
+
+      REGISTRY = load_registry
+      BY_KEY = REGISTRY.to_h { |component| [component.key, component] }.freeze
+      TOKEN_PRICED = REGISTRY.select { |component| component.token_key && component.cost_key }.freeze
+    end
+  end
+end