llm_cost_tracker 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d515abad24d5659f797d5ea0426d6111dc41baf78809181128546e29ac566db
-  data.tar.gz: 90da1dda161661423f6034f28d7bb359e06c39f48b9f4872cb0eba9a123f8948
+  metadata.gz: fa3f705baf280c2c2239b2dab3522fe7db9b60e26060b00fc08dcc039117da83
+  data.tar.gz: ea34bdad7cb0d7c9fb3233b40b609cea1361ded833ad130c4a7a7ce559b34758
 SHA512:
-  metadata.gz: aa7af4b5caca984cbcb4c8a7a267600251962e1879de8f3bff32d8a3f6e8d22888ba4a26036de09c36345566e3c309a2868012b66b5dcc970e52bcb6b5e444be
-  data.tar.gz: 932f2bb680690ed043eb719debddd58ac85c7f1cbbd0ec9c30c95f5595d71a5f70516b3d8d19ca65929856c4ade902a813da34b4de2053f553aa916eece66865
+  metadata.gz: 03c55866b522b36b0728f73fd0ae0075e0a42faa6f80c429865f120d2c597e0b0996665b6a82528c566a0f8554d7636dfd03d9ab600441dafd5a4f0233d3f56b
+  data.tar.gz: af01c4554912d80276bf54ed97aa379c2eaed791fa357ca135aa008fdcbdd41e365c236ac74c9ceb1982c0fbbf2538bc569df1690acb4b5758895dd48c4497b5

data/CHANGELOG.md

@@ -4,6 +4,52 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-29
+
+### Added
+
+- Durable ActiveRecord ingestion through `llm_cost_tracker_inbox_events` and `llm_cost_tracker_ingestor_leases`.
+- `llm_cost_tracker:add_ingestion` generator for upgrading existing ActiveRecord installs.
+- `LlmCostTracker.flush!` and `LlmCostTracker.shutdown!` for draining or stopping durable ingestion.
+- Doctor diagnostics for missing durable ingestion schema, stale pending inbox rows, and quarantined inbox rows.
+- PostgreSQL and MySQL smoke checks for ActiveRecord durable ingestion.
+
+### Changed
+
+- Fresh ActiveRecord installs now include durable ingestion tables, event IDs, and production indexes.
+- ActiveRecord budget totals now read stored period rollups plus pending inbox totals while durable ingestion is enabled.
+- ActiveRecord writes now use a durable inbox before batching ledger inserts and period rollup updates when ingestion tables are present.
+- Pricing lookup now caches normalized runtime price tables and model matches by configuration generation.
+- Stream capture now estimates buffered event size without serializing every captured event.
+- CSV export now selects only exported columns instead of loading full ActiveRecord objects.
+
+### Fixed
+
+- ActiveRecord rollups no longer double-count retried events when duplicate event IDs race across workers.
+- Invalid inbox rows are retried and quarantined without blocking healthy rows behind them.
+- Idle ingestors no longer acquire the leader lease while the inbox is empty.
+- ActiveRecord inbox writes now fail honestly when a separate connection is unavailable inside a caller transaction.
+- Ingestor shutdown/reset no longer lets an old sleeping thread resume as a second local ingestor.
+- `flush!` now returns `false` instead of raising when its timeout expires during ingestion.
+- ActiveRecord adapter family detection now works through known adapter class ancestry with an adapter-name fallback.
+- CSV export now emits `{}` for invalid stored tag payloads.
+
+## [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

data/README.md

@@ -167,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
@@ -231,7 +237,7 @@ Auth is your job. Examples for basic auth and Devise: [`docs/dashboard.md`](docs
 
 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 whenever the provider emits final-usage events.
+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
 
@@ -260,7 +266,6 @@ is still brief.
 ## Known limitations
 
 - `:block_requests` is best-effort under concurrency, not a transactional cap.
-- Official OpenAI and Anthropic SDK integrations cover non-streaming calls; streaming via those 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.
@@ -269,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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "csv"
+require "json"
 
 module LlmCostTracker
   class CallsController < ApplicationController
@@ -54,32 +55,45 @@ module LlmCostTracker
     end
 
     def render_csv(relation)
-      latency = LlmApiCall.latency_column?
+      fields = csv_fields
       CSV.generate do |csv|
-        headers = %w[tracked_at provider model input_tokens output_tokens total_tokens total_cost]
-        headers << "latency_ms" if latency
-        headers << "provider_response_id" if LlmApiCall.provider_response_id_column?
-        headers << "tags"
-        csv << headers
-
-        relation.each do |call|
-          row = [
-            call.tracked_at&.utc&.iso8601,
-            csv_safe(call.provider),
-            csv_safe(call.model),
-            call.input_tokens,
-            call.output_tokens,
-            call.total_tokens,
-            call.total_cost
-          ]
-          row << call.latency_ms if latency
-          row << csv_safe(call.provider_response_id) if LlmApiCall.provider_response_id_column?
-          row << csv_safe(call.parsed_tags.to_json)
-          csv << row
+        csv << fields.map(&:to_s)
+
+        relation.pluck(*fields).each do |values|
+          csv << fields.zip(values).map { |field, value| csv_value(field, value) }
         end
       end
     end
 
+    def csv_fields
+      fields = %i[tracked_at provider model input_tokens output_tokens total_tokens total_cost]
+      fields << :latency_ms if LlmApiCall.latency_column?
+      fields << :provider_response_id if LlmApiCall.provider_response_id_column?
+      fields << :tags
+      fields
+    end
+
+    def csv_value(field, value)
+      case field
+      when :tracked_at
+        value&.utc&.iso8601
+      when :provider, :model, :provider_response_id
+        csv_safe(value)
+      when :tags
+        csv_safe(csv_tags(value))
+      else
+        value
+      end
+    end
+
+    def csv_tags(value)
+      return value.transform_keys(&:to_s).to_json if value.is_a?(Hash)
+
+      JSON.parse(value || "{}").to_json
+    rescue JSON::ParserError
+      "{}"
+    end
+
     def csv_safe(value)
       return value if value.nil?
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "llm_cost_tracker/storage/active_record_store"
+
 module LlmCostTracker
   module Dashboard
     OverviewStatsData = Data.define(
@@ -77,7 +79,7 @@ module LlmCostTracker
           now = Time.now.utc
           month_start = now.beginning_of_month
           month_end = now.end_of_month
-          spent = LlmCostTracker::LlmApiCall.this_month.total_cost
+          spent = LlmCostTracker::Storage::ActiveRecordStore.monthly_total(time: now)
           elapsed_seconds = now - month_start
           total_seconds = month_end - month_start
           projected_spent = if spent.zero? || !elapsed_seconds.positive?

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

@@ -42,11 +42,10 @@ module LlmCostTracker
       end
 
       def build_sql
-        case connection.adapter_name
-        when /postgres/i then postgresql_sql
-        when /mysql/i    then mysql_sql
-        else                  sqlite_sql
-        end
+        return postgresql_sql if ActiveRecordAdapter.postgresql?(connection)
+        return mysql_sql if ActiveRecordAdapter.mysql?(connection)
+
+        sqlite_sql
       end
 
       def mysql_sql

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. Do not add dashboard-only aggregate tables until bounded indexed reads from `llm_api_calls` are no longer enough for the supported date range.
+
+## 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`

data/docs/configuration.md

@@ -0,0 +1,65 @@
+# Configuration
+
+Configuration is the contract between the host app and the ledger: where events
+go, which integrations are enabled, how attribution is attached, and how the app
+reacts when storage, pricing, or budgets need attention.
+
+The full option reference is moving here from the README. Until that migration is
+complete, the README anchors below remain canonical.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Quickstart](../README.md#quickstart)
+- [Capturing calls](../README.md#capturing-calls)
+- [Tags](../README.md#tags-who-burned-this-money)
+- [Pricing](../README.md#pricing)
+- [Budgets](../README.md#budgets)
+
+## Scope
+
+This page is scoped to:
+
+- `storage_backend`: `:log`, `:active_record`, and `:custom`; ActiveRecord capture uses a durable inbox when the ingestion migration is present
+- `default_tags`: static tags and per-request callable tags
+- `instrument`: RubyLLM and official SDK integrations
+- `prices_file` and `pricing_overrides`
+- `monthly_budget`, `daily_budget`, and `per_call_budget`
+- `budget_exceeded_behavior`
+- `storage_error_behavior`
+- `unknown_pricing_behavior`
+- `openai_compatible_providers`
+- `report_tag_breakdowns`
+
+## Minimal Production Config
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.storage_backend = :active_record
+  config.default_tags = -> { { environment: Rails.env } }
+  config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
+  config.instrument :openai
+end
+```
+
+Keep configuration at boot. Mutable shared settings are frozen after
+`configure` returns so request-time code cannot silently change global tracking
+behavior.
+
+Enabled SDK integrations are fail-fast. The client gem must be loaded, meet the
+minimum supported version, and expose the expected classes and methods before
+LLM Cost Tracker installs its wrapper.
+
+## Capture Verification
+
+After boot, run:
+
+```bash
+bin/rails llm_cost_tracker:verify_capture
+```
+
+For ActiveRecord storage, the task records a synthetic manual event inside a
+rollback and checks that notifications and persistence both work. For log and
+custom storage, it reports the configured capture path without invoking external
+sinks.

data/docs/cookbook.md

@@ -0,0 +1,185 @@
+# Cookbook
+
+Short integration recipes for common Ruby clients. Prefer SDK integrations or middleware. Use `track` and `track_stream` only as fallback helpers for unsupported clients.
+
+| Client | Best path | Why |
+|---|---|---|
+| RubyLLM | `config.instrument :ruby_llm` | The integration wraps RubyLLM's provider layer without adding a third-party instrumentation gem. |
+| Official `openai` gem | `config.instrument :openai` | The integration wraps SDK resource methods without changing call sites. |
+| Official `anthropic` gem | `config.instrument :anthropic` | The integration records returned message usage without changing call sites. |
+| `ruby-openai` | Faraday middleware | The client is built on Faraday and accepts middleware via the constructor block. |
+| OpenAI-compatible proxy | Faraday middleware | Use `ruby-openai` or a direct Faraday client against the proxy host. |
+| Custom Faraday client | Faraday middleware | The middleware can parse known provider responses automatically. |
+| Other clients | Adapter first, fallback helpers second | Add a stable integration instead of scattering per-call ledger code. |
+
+## RubyLLM
+
+Enable the integration once, then keep normal RubyLLM calls unchanged.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.instrument :ruby_llm
+end
+
+LlmCostTracker.with_tags(feature: "support_chat") do
+  RubyLLM.chat.ask("Hello")
+  RubyLLM.embed("text to embed")
+end
+```
+
+The RubyLLM integration supports `ruby_llm >= 1.14.1` and checks RubyLLM's provider contract at boot. Chat, embedding, and transcription calls are captured. Image generation, moderation, and tool execution are not recorded as separate ledger rows.
+
+## Official OpenAI SDK
+
+Enable the integration once, then keep normal `openai` gem calls unchanged.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.instrument :openai
+end
+
+client = OpenAI::Client.new(api_key: ENV["OPENAI_API_KEY"])
+
+client.responses.create(model: "gpt-4o", input: "Hello")
+client.chat.completions.create(
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello" }]
+)
+
+client.responses.stream(model: "gpt-4o", input: "Hello").each do |event|
+  puts event.type
+end
+
+client.responses.stream_raw(model: "gpt-4o", input: "Hello").each do |event|
+  puts event.type
+end
+
+client.chat.completions.stream_raw(
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello" }],
+  stream_options: { include_usage: true }
+).each do |event|
+  puts event
+end
+```
+
+The OpenAI SDK integration supports `openai >= 0.59.0`. Streaming calls are recorded after the returned stream is consumed. Chat Completions streams need `stream_options: { include_usage: true }` for final usage.
+
+## Official Anthropic SDK
+
+Enable the integration once, then keep normal `anthropic` gem calls unchanged.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.instrument :anthropic
+end
+
+client = Anthropic::Client.new(api_key: ENV["ANTHROPIC_API_KEY"])
+
+client.messages.create(
+  max_tokens: 1024,
+  model: "claude-sonnet-4-5-20250929",
+  messages: [{ role: "user", content: "Hello" }]
+)
+
+client.messages.stream(
+  max_tokens: 1024,
+  model: "claude-sonnet-4-5-20250929",
+  messages: [{ role: "user", content: "Hello" }]
+).each do |event|
+  puts event.type
+end
+
+client.messages.stream_raw(
+  max_tokens: 1024,
+  model: "claude-sonnet-4-5-20250929",
+  messages: [{ role: "user", content: "Hello" }]
+).each do |event|
+  puts event.type
+end
+```
+
+The Anthropic SDK integration supports `anthropic >= 1.36.0`. Streaming calls are recorded after the returned stream is consumed.
+
+## ruby-openai
+
+`ruby-openai` is a community client that occupies the same `OpenAI::Client` constant as the official gem; only one of the two can be loaded. `config.instrument :openai` is for the official gem. For `ruby-openai`, attach the Faraday middleware via the constructor block:
+
+```ruby
+client = OpenAI::Client.new(access_token: ENV["OPENAI_API_KEY"]) do |f|
+  f.use :llm_cost_tracker, tags: { feature: "chat" }
+end
+
+client.chat(
+  parameters: {
+    model: "gpt-4o",
+    messages: [{ role: "user", content: "Hello" }],
+    stream: proc { |chunk, _bytesize| puts chunk.dig("choices", 0, "delta", "content") },
+    stream_options: { include_usage: true }
+  }
+)
+```
+
+Use the constructor block on every client you build, or wrap client creation in your own factory.
+
+## Azure OpenAI
+
+Azure's v1 API works with OpenAI-compatible HTTP shapes, but pricing and deployment names are yours. Register the Azure host, use the Faraday middleware path, and keep Azure-specific prices in `prices_file` or `pricing_overrides`.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.openai_compatible_providers["my-resource.openai.azure.com"] = "azure_openai"
+end
+
+conn = Faraday.new(url: "https://my-resource.openai.azure.com") do |f|
+  f.use :llm_cost_tracker, tags: { feature: "chat" }
+  f.request :json
+  f.response :json
+  f.adapter Faraday.default_adapter
+end
+
+conn.post(
+  "/openai/v1/responses",
+  { model: "gpt-4o-prod", input: "Hello" },
+  { "api-key" => ENV.fetch("AZURE_OPENAI_API_KEY") }
+)
+```
+
+## Gemini API
+
+Google's official Gemini SDKs do not include Ruby. Use a Faraday client against the REST API so the Gemini parser can capture usage automatically.
+
+```ruby
+conn = Faraday.new(url: "https://generativelanguage.googleapis.com") do |f|
+  f.use :llm_cost_tracker, tags: { feature: "chat" }
+  f.request :json
+  f.response :json
+  f.adapter Faraday.default_adapter
+end
+
+conn.post(
+  "/v1beta/models/gemini-2.5-flash:generateContent?key=#{ENV.fetch("GOOGLE_API_KEY")}",
+  { contents: [{ role: "user", parts: [{ text: "Hello" }] }] }
+)
+```
+
+## LiteLLM proxy
+
+LiteLLM Proxy speaks an OpenAI-compatible HTTP shape, so register the proxy host once and keep using the normal middleware path.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.openai_compatible_providers["proxy.internal.example"] = "litellm"
+end
+
+client = OpenAI::Client.new(
+  access_token: ENV["LITELLM_API_KEY"],
+  uri_base: "https://proxy.internal.example"
+) do |f|
+  f.use :llm_cost_tracker, tags: { gateway: "litellm" }
+end
+
+client.chat(parameters: { model: "openai/gpt-5-mini", messages: [{ role: "user", content: "Hello" }] })
+```
+
+If your proxy exposes custom model IDs or discounts, add them in `prices_file` or `pricing_overrides`.

data/docs/dashboard.md

@@ -0,0 +1,38 @@
+# Dashboard
+
+The dashboard is a Rails Engine for humans reviewing spend, attribution, and data
+quality. It is server-rendered ERB, has no JavaScript bundle, and reads from the
+host app's `llm_api_calls` table.
+
+The detailed dashboard guide is moving here from the README: mounting, route
+constraints, authentication examples, page map, and operational notes.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Dashboard](../README.md#dashboard)
+- [Privacy](../README.md#privacy)
+- [Operations](operations.md)
+
+## Mounting
+
+```ruby
+mount LlmCostTracker::Engine => "/llm-costs"
+```
+
+Use `storage_backend = :active_record` for apps that mount the dashboard.
+
+## Pages
+
+- Overview: spend trend, budget status, anomaly banner, provider rollup, top models
+- Models: spend and usage by provider and model
+- Calls: filterable call ledger with CSV export
+- Tags: tag keys and tag value breakdowns
+- Data Quality: unknown pricing, untagged calls, missing latency, incomplete streams
+
+## Authentication
+
+The gem does not ship dashboard auth. Mount the engine behind the host app's
+existing authentication layer: Devise, basic auth, Cloudflare Access, or your own
+constraints.

data/docs/extending.md

@@ -0,0 +1,32 @@
+# Extending LLM Cost Tracker
+
+Extensions belong at clear boundaries: parsers for response shapes, integrations
+for SDK hooks, pricing files for rates, and custom storage for apps that own
+persistence themselves.
+
+The practical extension guide is moving here from the README. The lower-level
+contracts already live in the technical extension reference.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Capturing calls](../README.md#capturing-calls)
+- [Pricing](pricing.md)
+- [Technical extension points](technical/extension-points.md)
+
+## Extension Points
+
+- Custom parser: translate a provider response into `ParsedUsage`.
+- OpenAI-compatible host: register the host-to-provider mapping.
+- Custom storage: receive the canonical `Event` and write it elsewhere.
+- Notifications subscriber: observe `llm_request.llm_cost_tracker`.
+- Local price file: model gateway IDs, contract rates, or unsupported models.
+
+## Parser Boundary
+
+A parser matches request URLs, translates provider response shapes into
+`ParsedUsage`, and returns `nil` when the response is outside its contract.
+
+Do provider-specific translation at this boundary. Keep `Tracker`, storage,
+dashboard, and pricing in canonical ledger terms.

data/docs/operations.md

@@ -0,0 +1,44 @@
+# Operations
+
+Production use is mostly about choosing the right storage backend, keeping the
+database healthy, and understanding where the gem is intentionally best effort.
+
+The operational guide is moving here from the README: retention, tag storage,
+thread safety, connection pools, and deployment notes.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Privacy](../README.md#privacy)
+- [Known limitations](../README.md#known-limitations)
+- [Technical operational notes](technical/operational-notes.md)
+
+## Production Defaults
+
+- Use `storage_backend = :active_record` for the shared ledger, dashboard, and
+  cross-process budget guardrails.
+- Size the ActiveRecord connection pool for your app plus ledger writes.
+- Keep `storage_error_behavior = :warn` unless losing the LLM response is better
+  than losing the ledger event.
+- Treat `:block_requests` as a guardrail, not a hard quota.
+- Keep `default_tags` callables fast and thread-safe.
+
+## Retention
+
+Retention is explicit. Use the prune task when the ledger should not grow
+forever:
+
+```bash
+DAYS=90 bin/rails llm_cost_tracker:prune
+```
+
+When ActiveRecord period rollups are installed, pruning decrements the
+affected daily and monthly buckets in the same batch transaction as the ledger
+delete.
+
+## Data Shape
+
+Tags are JSONB with a GIN index on PostgreSQL and JSON text elsewhere. The
+dashboard and query helpers work across supported adapters, but PostgreSQL is the
+strongest path for large tag-heavy ledgers.