llm_cost_tracker 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc48791f2f21576da80d4a05ed149290dd309ab9d6f9af3774df56cc389224a4
-  data.tar.gz: bb9de40f1669907210da3321cb4cc85999be8d748afa39a16f9fae7bceea9378
+  metadata.gz: d3fe81fdf7b12f977d7dfc4aa86f629e8b5ad6e099100bfbfe1b18507db17fff
+  data.tar.gz: dffe0c0ebeb30fa111273b654141ee06e1275426846796b1749435429da3414f
 SHA512:
-  metadata.gz: 5a8a68b4f567fbfce3158df20a1e34b6bb6a5ea4a4162b28206bbfe099c1b36288e89f8db29dcc60617da44d7d07acdf6b38d3747f4ffb683dedfc059d1f4089
-  data.tar.gz: 5f8493e21e71e9ce43ad7ac33386f1dc39a03ac0b48cc0bad71232a21b2e2ebfc3bddd5be6b2109dbdadecbad47f79fad0c40519394fbdfad74a9a5ec5aa158c
+  metadata.gz: 4849f0d0b09d640ed3a902bbc19a975e576b0539d2c71eac3165199eed196ecd88f249ff1d571c43b2686d59466dde26a0467f984c2cbb7804a5f771e184df31
+  data.tar.gz: 8aa17efc9dd68b1489cdc69351a67fe2398c35720750cf1440f215bceeef0392c9f3af1d41ebd444ddcd9876c2c1e612ea50d6403fb7f650735fc9d9161a2a85

data/CHANGELOG.md

@@ -4,6 +4,49 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.5.3] - 2026-04-28
+
+### Added
+
+- Official OpenAI SDK streaming capture for Responses streams, Responses raw streams, Responses retrieve streams, and Chat Completions raw streams.
+- Official Anthropic SDK streaming capture for Messages streams and raw streams.
+- Capture verification via `llm_cost_tracker:verify_capture` and expanded doctor capture diagnostics.
+- Pricing explanation via `LlmCostTracker::Pricing.explain` and `llm_cost_tracker:prices:explain`.
+- Extensible storage and SDK integration registries via `Storage.register` and `Integrations.register`.
+
+### Fixed
+
+- OpenAI Responses stream parsing now reads final usage from completed response events.
+- Incomplete price entries now return unknown pricing instead of raising `TypeError`.
+- Retention pruning now keeps ActiveRecord period rollups in sync when deleting rows inside active budget windows.
+
+## [0.5.2] - 2026-04-27
+
+### Added
+
+- RubyLLM SDK integration for chat, embedding, and transcription calls.
+- Tag guardrails for redacted tag keys, maximum tag count, and maximum tag value byte size.
+
+### Changed
+
+- SDK integrations now validate minimum versions and method contracts before installing wrappers.
+- `config.instrument :all` now includes RubyLLM.
+- Dashboard date filters now reject one-sided, reversed, and over-366-day ranges.
+- Dashboard provider/model/tag option lists and tag value breakdowns now cap rendered rows.
+- Reports now cap rendered breakdown groups while keeping complete structured report data available.
+- Stream capture now enforces a shared 1 MiB buffer cap and records unknown usage on overflow.
+- Price refresh, price scrape, and local price registry reads now enforce response or file size caps.
+- Retention pruning now rejects non-positive batch sizes and invalid cutoffs before deleting rows.
+- The install generator now warns to mount the dashboard behind host-app admin authentication.
+
+### Fixed
+
+- OpenAI SDK integration now separates cached input tokens from regular input tokens.
+- OpenAI and Gemini parsers now compute total tokens when provider responses omit totals.
+- CSV export now prefixes formula-like values even when they have leading whitespace.
+- Tag chips now truncate oversized values and tooltips.
+- Report tag breakdown keys are validated at configuration time.
+
 ## [0.5.1] - 2026-04-27
 
 ### Changed

data/README.md

@@ -20,7 +20,7 @@ Add to your Gemfile alongside whatever LLM client you already use:
 
 ```ruby
 gem "llm_cost_tracker"
-gem "openai"  # or "anthropic", or your existing client
+gem "openai"  # or "anthropic", "ruby_llm", or your existing client
 ```
 
 Install, migrate, verify:
@@ -55,7 +55,7 @@ Visit `/llm-costs` for the dashboard. **Mount it behind your app's auth before d
 ## What you get
 
 - Local ActiveRecord ledger of every call: provider, model, token breakdown, cost, latency, tags, response IDs
-- Auto-capture for the official `openai` and `anthropic` Ruby SDKs, plus Faraday middleware for `ruby-openai`, the Gemini REST API, and any client you can inject middleware into
+- Auto-capture for RubyLLM and the official `openai` and `anthropic` Ruby SDKs, plus Faraday middleware for `ruby-openai`, the Gemini REST API, and any client you can inject middleware into
 - Server-rendered dashboard (plain ERB, zero JavaScript) with overview, models, calls, tags, CSV export, and a data-quality page
 - Local pricing snapshots refreshed daily from the official provider pricing pages, applied with `bin/rails llm_cost_tracker:prices:refresh`
 - Monthly / daily / per-call budget guardrails with notify, raise, or block-requests behaviour
@@ -73,13 +73,13 @@ Visit `/llm-costs` for the dashboard. **Mount it behind your app's auth before d
 
 Three paths, in order of preference. Use the first one that fits your stack.
 
-### 1. Official SDK integrations
+### 1. SDK integrations
 
-Drop-in for the official `openai` and `anthropic` gems. `config.instrument` patches the SDK's resource methods so you don't change a single call site:
+Drop-in for RubyLLM and the official `openai` and `anthropic` gems. `config.instrument` patches tested SDK methods so you don't change a single call site:
 
 ```ruby
 LlmCostTracker.configure do |config|
-  config.instrument :openai      # or :anthropic, or :all
+  config.instrument :openai      # or :anthropic / :ruby_llm
 end
 
 LlmCostTracker.with_tags(feature: "support_chat") do
@@ -93,7 +93,9 @@ end
 
 Captures usage, model, latency, response ID, cache tokens, and reasoning tokens whenever the SDK exposes them. Provider SDKs are not added as gem dependencies — you install whichever you actually use.
 
-This patches **only** the official Ruby SDKs. `ruby-openai` (alexrudall) and any custom client go through Faraday middleware below.
+Enabled integrations are checked at boot: the client gem must be loaded, meet the minimum supported version, and expose the expected classes and methods. If the contract check fails, boot raises instead of silently missing spend.
+
+This patches **only** RubyLLM and the official Ruby SDKs. `ruby-openai` (alexrudall) and any custom client go through Faraday middleware below.
 
 ### 2. Faraday middleware
 
@@ -165,6 +167,12 @@ Refresh on demand from the maintained snapshot:
 bin/rails llm_cost_tracker:prices:refresh
 ```
 
+Explain why a model is priced or unknown:
+
+```bash
+PROVIDER=openai MODEL=gpt-4o bin/rails llm_cost_tracker:prices:explain
+```
+
 Precedence is `pricing_overrides` → `prices_file` → bundled. Provider-qualified keys like `openai/gpt-4o-mini` win over model-only keys. Full pricing reference: [`docs/pricing.md`](docs/pricing.md).
 
 ## Budgets
@@ -227,7 +235,9 @@ Auth is your job. Examples for basic auth and Devise: [`docs/dashboard.md`](docs
 | Other OpenAI-compatible hosts | Configurable | Register the host via `config.openai_compatible_providers` |
 | Anything else | Configurable | Custom parser — see [`docs/extending.md`](docs/extending.md) |
 
-Endpoints covered end-to-end: OpenAI Chat Completions / Responses / Completions / Embeddings, Anthropic Messages, Gemini `generateContent` and `streamGenerateContent`, plus their OpenAI-compatible equivalents. Streaming is captured for Faraday paths whenever the provider emits final-usage events.
+RubyLLM chat, embedding, and transcription calls are captured through RubyLLM's provider layer when `config.instrument :ruby_llm` is enabled.
+
+Endpoints covered end-to-end: OpenAI Chat Completions / Responses / Completions / Embeddings, Anthropic Messages, Gemini `generateContent` and `streamGenerateContent`, plus their OpenAI-compatible equivalents. Streaming is captured for Faraday paths and official OpenAI / Anthropic SDK stream helpers whenever the provider emits final-usage events.
 
 ## Privacy
 
@@ -256,7 +266,6 @@ is still brief.
 ## Known limitations
 
 - `:block_requests` is best-effort under concurrency, not a transactional cap.
-- Official SDK integrations cover non-streaming calls; streaming via the SDKs falls back to Faraday middleware or `track_stream`.
 - Streaming usage capture relies on the provider emitting a final-usage event. Missing events are stored with `usage_source: "unknown"` so they appear on the data-quality page rather than vanishing.
 - `provider_response_id` is stored only when the provider exposes a stable ID. Gemini is best-effort and varies by endpoint.
 - Cache write TTL variants on Anthropic (1h vs 5min writes) are not modeled separately yet.
@@ -265,7 +274,7 @@ is still brief.
 
 ```bash
 bundle install
-bin/check       # rubocop + rspec
+bin/check       # rubocop + rspec + coverage gate
 ```
 
 Architecture rules and conventions for contributions live in [`AGENTS.md`](AGENTS.md) and [`docs/architecture.md`](docs/architecture.md).

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -84,7 +84,8 @@ module LlmCostTracker
       return value if value.nil?
 
       string = value.to_s
-      CSV_FORMULA_PREFIXES.include?(string[0]) ? "'#{string}" : string
+      stripped = string.lstrip
+      CSV_FORMULA_PREFIXES.include?(stripped[0]) ? "'#{string}" : string
     end
   end
 end

data/app/controllers/llm_cost_tracker/dashboard_controller.rb

@@ -3,7 +3,9 @@
 module LlmCostTracker
   class DashboardController < ApplicationController
     def index
-      @from_date, @to_date = overview_range
+      range = Dashboard::DateRange.call(params: params)
+      @from_date = range.from
+      @to_date = range.to
       prev_from, prev_to = previous_range
       filter_params = LlmCostTracker::ParameterHash.to_hash(params)
       scope = Dashboard::Filter.call(
@@ -23,25 +25,11 @@ module LlmCostTracker
 
     private
 
-    def overview_range
-      to_date = parsed_date(params[:to]) || Date.current
-      from_date = parsed_date(params[:from]) || (to_date - 29)
-      [from_date, to_date]
-    end
-
     def previous_range
       span_days = (@to_date - @from_date).to_i + 1
       prev_to = @from_date - 1
       prev_from = prev_to - (span_days - 1)
       [prev_from, prev_to]
     end
-
-    def parsed_date(value)
-      return nil if value.to_s.strip.empty?
-
-      Date.iso8601(value.to_s)
-    rescue ArgumentError
-      nil
-    end
   end
 end

data/app/controllers/llm_cost_tracker/tags_controller.rb

@@ -8,12 +8,13 @@ module LlmCostTracker
 
     def show
       @tag_key = params[:key]
-      @rows = Dashboard::TagBreakdown.call(scope: Dashboard::Filter.call(params: params), key: @tag_key)
-      @total_calls = @rows.sum(&:calls)
-
-      tagged_rows = @rows.reject { |r| r.value == "(untagged)" }
-      @tagged_calls = tagged_rows.sum(&:calls)
-      @distinct_values = tagged_rows.size
+      breakdown = Dashboard::TagBreakdown.call(scope: Dashboard::Filter.call(params: params), key: @tag_key)
+      @rows = breakdown.rows
+      @total_calls = breakdown.total_calls
+      @tagged_calls = breakdown.tagged_calls
+      @distinct_values = breakdown.distinct_values
+      @tag_value_limit = breakdown.limit
+      @tag_values_limited = breakdown.limited?
     end
   end
 end

data/app/helpers/llm_cost_tracker/application_helper.rb

@@ -4,6 +4,9 @@ require "json"
 
 module LlmCostTracker
   module ApplicationHelper
+    TAG_VALUE_SUMMARY_BYTES = 80
+    TAG_TOOLTIP_BYTES = 512
+
     include DashboardFilterHelper
     include DashboardFilterOptionsHelper
     include DashboardQueryHelper
@@ -116,6 +119,10 @@ module LlmCostTracker
       visible
     end
 
+    def tag_chips_title(tags)
+      truncate_text(safe_json(tags), TAG_TOOLTIP_BYTES)
+    end
+
     def budget_fill_modifier(percent)
       percent = percent.to_f
       return "lct-budget-fill--over" if percent >= 100.0
@@ -143,12 +150,20 @@ module LlmCostTracker
     end
 
     def tag_value_summary(value)
-      case value
-      when Hash, Array
-        JSON.generate(value)
-      else
-        value.to_s
-      end
+      string = case value
+               when Hash, Array
+                 JSON.generate(value)
+               else
+                 value.to_s
+               end
+
+      truncate_text(string, TAG_VALUE_SUMMARY_BYTES)
+    end
+
+    def truncate_text(string, limit)
+      return string if string.bytesize <= limit
+
+      "#{string.byteslice(0, limit).to_s.encode('UTF-8', invalid: :replace, undef: :replace)}..."
     end
   end
 end

data/app/helpers/llm_cost_tracker/dashboard_filter_options_helper.rb

@@ -2,6 +2,8 @@
 
 module LlmCostTracker
   module DashboardFilterOptionsHelper
+    MAX_FILTER_OPTIONS = 100
+
     def provider_filter_options(filter_params: params)
       filter_options_for(:provider, filter_params: filter_params)
     end
@@ -19,7 +21,7 @@ module LlmCostTracker
       )
       values = LlmCostTracker::Dashboard::Filter.call(params: scope_params)
                                                 .where.not(column => [nil, ""])
-                                                .distinct.order(column).pluck(column)
+                                                .distinct.order(column).limit(MAX_FILTER_OPTIONS).pluck(column)
       current = source[column.to_s].presence || source[column].presence
       values.unshift(current) if current && !values.include?(current)
       values

data/app/services/llm_cost_tracker/dashboard/date_range.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Dashboard
+    class DateRange
+      DEFAULT_DAYS = 30
+      MAX_DAYS = 366
+
+      attr_reader :from, :to
+
+      def self.call(params:, today: Date.current)
+        new(params: params, today: today)
+      end
+
+      def self.parse(params, key)
+        value = LlmCostTracker::ParameterHash.with_indifferent_access(params)[key].to_s.strip
+        return nil if value.empty?
+
+        Date.iso8601(value)
+      rescue ArgumentError
+        nil
+      end
+
+      def self.validate!(from:, to:)
+        return if from.nil? && to.nil?
+
+        raise InvalidFilterError, "from and to dates must be provided together" if from.nil? || to.nil?
+        raise InvalidFilterError, "from date must be on or before to date" if from > to
+        return if ((to - from).to_i + 1) <= MAX_DAYS
+
+        raise InvalidFilterError, "date range cannot exceed #{MAX_DAYS} days"
+      end
+
+      def initialize(params:, today:)
+        @to = self.class.parse(params, :to) || today
+        @from = self.class.parse(params, :from) || (@to - (DEFAULT_DAYS - 1))
+        self.class.validate!(from: @from, to: @to)
+        freeze
+      end
+    end
+  end
+end

data/app/services/llm_cost_tracker/dashboard/filter.rb

@@ -31,9 +31,12 @@ module LlmCostTracker
       attr_reader :scope, :params
 
       def apply_date_filters(relation)
-        from = parse_date(:from)&.beginning_of_day
-        to = parse_date(:to)&.end_of_day
+        from_date = parse_date(:from)
+        to_date = parse_date(:to)
+        Dashboard::DateRange.validate!(from: from_date, to: to_date)
 
+        from = from_date&.beginning_of_day
+        to = to_date&.end_of_day
         relation = relation.where(tracked_at: from..) if from
         relation = relation.where(tracked_at: ..to) if to
         relation
@@ -89,12 +92,7 @@ module LlmCostTracker
       end
 
       def parse_date(key)
-        value = normalized_string(params[key])
-        return nil if value.nil?
-
-        Date.iso8601(value)
-      rescue ArgumentError
-        nil
+        Dashboard::DateRange.parse(params, key)
       end
 
       def normalized_string(value)

data/app/services/llm_cost_tracker/dashboard/spend_anomaly.rb

@@ -65,11 +65,12 @@ module LlmCostTracker
 
         scope
           .where(tracked_at: window)
-          .pluck(:provider, :model, :tracked_at, :total_cost)
-          .each do |provider, model, tracked_at, total_cost|
-            next if total_cost.nil?
-
-            grouped[[provider, model]][tracked_at.to_date] += total_cost.to_f
+          .where.not(total_cost: nil)
+          .group(:provider, :model)
+          .group_by_period(:day)
+          .sum(:total_cost)
+          .each do |(provider, model, day), total_cost|
+            grouped[[provider, model]][Date.iso8601(day.to_s)] += total_cost.to_f
           end
 
         grouped

data/app/services/llm_cost_tracker/dashboard/tag_breakdown.rb

@@ -9,28 +9,54 @@ module LlmCostTracker
       :average_cost_per_call
     )
 
+    TagBreakdownResult = Data.define(
+      :rows,
+      :total_calls,
+      :tagged_calls,
+      :distinct_values,
+      :limit
+    ) do
+      def limited? = distinct_values > rows.size
+    end
+
     class TagBreakdown
+      DEFAULT_LIMIT = 100
+
       class << self
-        def call(key:, scope: LlmCostTracker::LlmApiCall.all)
-          new(scope: scope, key: key).rows
+        def call(key:, scope: LlmCostTracker::LlmApiCall.all, limit: DEFAULT_LIMIT)
+          new(scope: scope, key: key, limit: limit).result
         end
       end
 
-      def initialize(scope:, key:)
+      def initialize(scope:, key:, limit:)
         @scope = scope
         @key = LlmCostTracker::TagKey.validate!(key, error_class: LlmCostTracker::InvalidFilterError)
+        @limit = normalized_limit(limit)
+        @connection = LlmCostTracker::LlmApiCall.connection
       end
 
-      def rows
-        costs = scope.cost_by_tag(key)
-        counts = counts_by_tag
+      def result
+        counts = summary_counts
 
-        costs.map do |value, total_cost|
-          calls = counts[value].to_i
-          total_cost = total_cost.to_f
+        TagBreakdownResult.new(
+          rows: rows,
+          total_calls: counts.fetch(:total_calls),
+          tagged_calls: counts.fetch(:tagged_calls),
+          distinct_values: counts.fetch(:distinct_values),
+          limit: limit
+        )
+      end
 
+      private
+
+      attr_reader :scope, :key, :limit, :connection
+
+      def rows
+        connection.select_all(rows_sql).map do |row|
+          calls = row["calls_count"].to_i
+          total_cost = row["total_cost_sum"].to_f
           TagBreakdownRow.new(
-            value: value,
+            value: LlmCostTracker::LlmApiCall.tag_value_label(row["tag_value"]),
             calls: calls,
             total_cost: total_cost,
             average_cost_per_call: calls.positive? ? total_cost / calls : 0.0
@@ -38,18 +64,48 @@ module LlmCostTracker
         end
       end
 
-      private
+      def summary_counts
+        row = connection.select_one(summary_sql) || {}
+        {
+          total_calls: row["total_calls"].to_i,
+          tagged_calls: row["tagged_calls"].to_i,
+          distinct_values: row["distinct_values"].to_i
+        }
+      end
 
-      attr_reader :scope, :key
+      def rows_sql
+        <<~SQL.squish
+          SELECT #{tag_expression} AS tag_value,
+                 COUNT(*) AS calls_count,
+                 COALESCE(SUM(sub.total_cost), 0) AS total_cost_sum
+          FROM (#{scope.to_sql}) AS sub
+          WHERE #{tag_present_predicate}
+          GROUP BY #{tag_expression}
+          ORDER BY total_cost_sum DESC, calls_count DESC, tag_value ASC
+          LIMIT #{limit}
+        SQL
+      end
 
-      def counts_by_tag
-        scope.group_by_tag(key).count.each_with_object(Hash.new(0)) do |(raw, count), hash|
-          hash[label(raw)] += count.to_i
-        end
+      def summary_sql
+        <<~SQL.squish
+          SELECT COUNT(*) AS total_calls,
+                 COALESCE(SUM(CASE WHEN #{tag_present_predicate} THEN 1 ELSE 0 END), 0) AS tagged_calls,
+                 COUNT(DISTINCT CASE WHEN #{tag_present_predicate} THEN #{tag_expression} END) AS distinct_values
+          FROM (#{scope.to_sql}) AS sub
+        SQL
+      end
+
+      def tag_present_predicate
+        "#{tag_expression} IS NOT NULL AND #{tag_expression} != ''"
+      end
+
+      def tag_expression
+        @tag_expression ||= LlmCostTracker::LlmApiCall.tag_value_expression(key, table_name: "sub")
       end
 
-      def label(value)
-        value.nil? || value == "" ? "(untagged)" : value.to_s
+      def normalized_limit(value)
+        value = value.to_i
+        value.positive? ? [value, DEFAULT_LIMIT].min : DEFAULT_LIMIT
       end
     end
   end

data/app/services/llm_cost_tracker/dashboard/tag_key_explorer.rb

@@ -5,15 +5,18 @@ module LlmCostTracker
     TagKeyRow = Data.define(:key, :calls_count, :distinct_values)
 
     class TagKeyExplorer
+      DEFAULT_LIMIT = 100
+
       class << self
-        def call(scope: LlmCostTracker::LlmApiCall.all)
-          new(scope: scope).rows
+        def call(scope: LlmCostTracker::LlmApiCall.all, limit: DEFAULT_LIMIT)
+          new(scope: scope, limit: limit).rows
         end
       end
 
-      def initialize(scope:)
+      def initialize(scope:, limit:)
         @scope = scope
         @connection = LlmCostTracker::LlmApiCall.connection
+        @limit = normalized_limit(limit)
       end
 
       def rows
@@ -32,7 +35,7 @@ module LlmCostTracker
 
       private
 
-      attr_reader :scope, :connection
+      attr_reader :scope, :connection, :limit
 
       def subquery
         scope.to_sql
@@ -62,6 +65,7 @@ module LlmCostTracker
             AND sub.tags != ''
           GROUP BY jt.key
           ORDER BY calls_count DESC
+          LIMIT #{limit}
         SQL
       end
 
@@ -76,6 +80,7 @@ module LlmCostTracker
             AND sub.tags::jsonb <> '{}'::jsonb
           GROUP BY key
           ORDER BY calls_count DESC
+          LIMIT #{limit}
         SQL
       end
 
@@ -91,8 +96,14 @@ module LlmCostTracker
             AND sub.tags != ''
           GROUP BY je.key
           ORDER BY calls_count DESC
+          LIMIT #{limit}
         SQL
       end
+
+      def normalized_limit(value)
+        value = value.to_i
+        value.positive? ? [value, DEFAULT_LIMIT].min : DEFAULT_LIMIT
+      end
     end
   end
 end

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

@@ -2,7 +2,7 @@
 <% if entries.empty? %>
   <span class="lct-tag-empty">(untagged)</span>
 <% else %>
-  <span class="lct-tag-chips" title="<%= safe_json(tags) %>">
+  <span class="lct-tag-chips" title="<%= tag_chips_title(tags) %>">
     <% entries.each do |entry| %>
       <% if entry[:more] %>
         <span class="lct-tag-chip lct-tag-chip-more">+<%= entry[:more] %></span>

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

@@ -50,6 +50,10 @@
     <span><strong><%= percent(coverage_percent(@tagged_calls, @total_calls)) %></strong> coverage</span>
     <span><strong><%= number(@distinct_values) %></strong> distinct values</span>
   </p>
+
+  <% if @tag_values_limited %>
+    <p class="lct-toolbar-note">Showing top <%= number(@tag_value_limit) %> values by spend.</p>
+  <% end %>
 </section>
 
 <% if @rows.empty? %>

data/docs/architecture.md

@@ -0,0 +1,28 @@
+# Architecture
+
+LLM Cost Tracker is a provider-agnostic billing ledger. Core code should model durable billing concepts, not the naming quirks of one provider or one model family.
+
+Core vocabulary belongs in provider-neutral terms:
+
+- `input_tokens`
+- `cache_read_input_tokens`
+- `cache_write_input_tokens`
+- `output_tokens`
+- `hidden_output_tokens`
+- `pricing_mode`
+- `provider_response_id`
+
+Provider-specific names belong only at ingestion boundaries: parsers and stream adapters. Those adapters translate raw fields into the canonical ledger vocabulary before data reaches `Tracker`, `Pricing`, storage, dashboard services, or reports.
+
+Pricing logic should prefer generic mechanisms over provider branches. Use provider/model price entries only for lookup and rate selection. Use `pricing_mode` plus mode-prefixed price keys for alternate billing modes instead of adding model-specific conditionals.
+
+Tags remain the extension point for app-specific attribution such as tenant, user, feature, trace, job, workflow, or agent session. Do not promote those dimensions into first-class columns unless the ledger itself needs them for provider-agnostic billing behavior.
+
+Hot-path guardrails must not aggregate over the growing call ledger. ActiveRecord period budgets should read maintained rows in `llm_cost_tracker_period_totals`; dashboard analytics may run grouped queries because they are user-initiated reporting paths.
+
+## Technical Docs
+
+- [Module map](technical/module-map.md)
+- [Data flow](technical/data-flow.md)
+- [Extension points](technical/extension-points.md)
+- [Operational notes](technical/operational-notes.md)

data/docs/budgets.md

@@ -0,0 +1,45 @@
+# Budgets and Guardrails
+
+Budgets are safety rails for a Rails app using LLMs in production. They are not
+invoice reconciliation and they are not a transactional quota system.
+
+The full behavior reference is moving here from the README: monthly, daily, and
+per-call budgets; notification payloads; preflight behavior; and failure modes.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Budgets](../README.md#budgets)
+- [Known limitations](../README.md#known-limitations)
+- [Operations](operations.md)
+
+## Behaviors
+
+- `:notify`: call `on_budget_exceeded` after a priced event crosses a limit.
+- `:raise`: record the event, then raise `BudgetExceededError`.
+- `:block_requests`: preflight future calls when stored period totals are
+  already over budget.
+
+```ruby
+config.monthly_budget = 500.00
+config.daily_budget = 50.00
+config.per_call_budget = 2.00
+config.budget_exceeded_behavior = :block_requests
+```
+
+`:block_requests` needs ActiveRecord storage for shared period totals. Under
+concurrency it stops the next request after overspend is visible; it does not
+make provider spend transactional.
+
+## Error Payload
+
+`BudgetExceededError` exposes:
+
+- `budget_type`
+- `total`
+- `budget`
+- `monthly_total`
+- `daily_total`
+- `call_cost`
+- `last_event`