llm_cost_tracker 0.6.0 → 0.7.0

data/lib/llm_cost_tracker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmCostTracker
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/llm_cost_tracker.rb

@@ -69,8 +69,8 @@ module LlmCostTracker
         @configuration_generation = @configuration_generation.to_i + 1
         current
       end
-      Integrations.install!
-      warn_for_configuration!(config)
+      Integrations::Registry.install!
+      config
     end
 
     def reset_configuration!
@@ -151,18 +151,6 @@ module LlmCostTracker
       collector&.finish!(errored: true)
       raise
     end
-
-    private
-
-    def warn_for_configuration!(config = configuration)
-      return unless config.budget_exceeded_behavior == :block_requests
-      return if config.active_record?
-
-      Logging.warn(
-        ":block_requests requires storage_backend = :active_record for monthly and daily preflight; " \
-        "preflight blocking will be skipped."
-      )
-    end
   end
 end
 

data/lib/tasks/llm_cost_tracker.rake

@@ -24,7 +24,7 @@ namespace :llm_cost_tracker do
 
   desc "Print an LLM cost report from ActiveRecord storage"
   task report: :environment do
-    days = (ENV["DAYS"] || LlmCostTracker::Report::DEFAULT_DAYS).to_i
+    days = (ENV["DAYS"] || LlmCostTracker::ReportData::DEFAULT_DAYS).to_i
     puts LlmCostTracker::Report.generate(days: days)
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_cost_tracker
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Sergii Khomenko
@@ -10,6 +10,26 @@ bindir: bin
 cert_chain: []
 date: 2026-04-29 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -65,7 +85,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: activerecord
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -74,7 +94,7 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -99,25 +119,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.16'
 - !ruby/object:Gem::Dependency
-  name: railties
+  name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.1'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '9.0'
+        version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.1'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '9.0'
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -188,26 +202,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.4'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.4'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -224,8 +218,9 @@ dependencies:
         version: '3.0'
 description: Tracks token usage, latency, and estimated costs for RubyLLM, OpenAI,
   Anthropic, Google Gemini, OpenRouter, DeepSeek, and OpenAI-compatible APIs. Works
-  through Faraday middleware or explicit track/track_stream helpers, with ActiveRecord
-  storage, tag-based attribution, price sync tasks, and budget guardrails.
+  through Rails SDK integrations, Faraday middleware, or explicit track/track_stream
+  helpers, with ActiveRecord storage, tag-based attribution, price sync tasks, and
+  budget guardrails.
 email:
 - sergey@mm.st
 executables: []
@@ -283,23 +278,6 @@ files:
 - app/views/llm_cost_tracker/tags/index.html.erb
 - app/views/llm_cost_tracker/tags/show.html.erb
 - config/routes.rb
-- docs/architecture.md
-- docs/budgets.md
-- docs/configuration.md
-- docs/cookbook.md
-- docs/dashboard-overview.png
-- docs/dashboard.md
-- docs/extending.md
-- docs/operations.md
-- docs/pricing.md
-- docs/querying.md
-- docs/streaming.md
-- docs/technical/README.md
-- docs/technical/data-flow.md
-- docs/technical/extension-points.md
-- docs/technical/module-map.md
-- docs/technical/operational-notes.md
-- docs/upgrading.md
 - lib/llm_cost_tracker.rb
 - lib/llm_cost_tracker/active_record_adapter.rb
 - lib/llm_cost_tracker/assets.rb
@@ -307,13 +285,11 @@ files:
 - lib/llm_cost_tracker/capture_verifier.rb
 - lib/llm_cost_tracker/configuration.rb
 - lib/llm_cost_tracker/configuration/instrumentation.rb
-- lib/llm_cost_tracker/configuration/storage_backend.rb
 - lib/llm_cost_tracker/cost.rb
 - lib/llm_cost_tracker/doctor.rb
 - lib/llm_cost_tracker/doctor/capture_check.rb
 - lib/llm_cost_tracker/doctor/ingestion_check.rb
 - lib/llm_cost_tracker/engine.rb
-- lib/llm_cost_tracker/engine_compatibility.rb
 - lib/llm_cost_tracker/errors.rb
 - lib/llm_cost_tracker/event.rb
 - lib/llm_cost_tracker/event_metadata.rb
@@ -392,10 +368,7 @@ files:
 - lib/llm_cost_tracker/storage/active_record_rollup_upsert_sql.rb
 - lib/llm_cost_tracker/storage/active_record_rollups.rb
 - lib/llm_cost_tracker/storage/active_record_store.rb
-- lib/llm_cost_tracker/storage/custom_backend.rb
-- lib/llm_cost_tracker/storage/dispatcher.rb
-- lib/llm_cost_tracker/storage/log_backend.rb
-- lib/llm_cost_tracker/storage/registry.rb
+- lib/llm_cost_tracker/storage/writer.rb
 - lib/llm_cost_tracker/stream_capture.rb
 - lib/llm_cost_tracker/stream_collector.rb
 - lib/llm_cost_tracker/tag_accessors.rb
@@ -438,5 +411,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Self-hosted LLM usage and cost tracking for Ruby and Rails
+summary: Rails-native LLM usage and cost tracking with ActiveRecord storage
 test_files: []

data/docs/architecture.md

@@ -1,28 +0,0 @@
-# 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

@@ -1,45 +0,0 @@
-# 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

@@ -1,65 +0,0 @@
-# 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

@@ -1,185 +0,0 @@
-# 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

@@ -1,38 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,44 +0,0 @@
-# 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.