llm_cost_tracker 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7b40f1010c79358da89ffdd10637f59fa90e24aa0f50aec364828d2e2cbf5b9
-  data.tar.gz: d12d1cf407b87afd6e1084c22ceda143c7ab9bf5e6ea6825d70a8e24969cafa5
+  metadata.gz: 0d1192ed209333057bd2522173d05530b4f45c6bb63242189c75354a83b5a746
+  data.tar.gz: 486555221b66a0da6cb867d207fb76349f0d56a23da623418da35aab7672875f
 SHA512:
-  metadata.gz: 949157f0a6718bc03f8f0d825982ed732df2754ddf1e4ee07b18522b0e20cc4367a97c599071bcda95bbdda4dde0e160f5d586a9b42a0dd8b1f3c89910286547
-  data.tar.gz: 9ea9007142d157446271bcf81bc4786e4b22a00f6e353dc2e3dc26c1be12d9abf88aed8d8852da37778b5fe3f71fcd4422c6153d8a531f195adaf0d0b9bb8dd2
+  metadata.gz: 8e74531effe3fc425de0384c13c7717c54b8be8d683493c92665b356ed8142d2629c9ce555f5fff703c2cd4a676d69e82efb39de767fc75fdbdcabdca9289f2c
+  data.tar.gz: 38e9744e157248e67bebcdd818b356c06b923d75a216b406f96f0b1b10368d4a118cbb9593461e2a19d19bdb5b10fc115c2f871d15fcf8669e656ad8ea8e034a

data/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.3] - 2026-04-18
+
+### Thread-safety, pricing UX, and internal hardening
+
+**Thread-safety**
+
+- Guard `PriceRegistry.file_prices` and `Pricing.sorted_price_keys` memoization with mutexes.
+
+**Pricing UX**
+
+- Warn on unknown keys in local prices files.
+- Add `llm_cost_tracker:prices` generator for creating a local price override template.
+- Document that budget enforcement skips events with unknown pricing.
+
+**Onboarding UX**
+
+- Add callable Faraday `tags:` support for per-request Rails attribution with `Current`.
+- Add `llm_cost_tracker:report` rake task for a quick terminal cost report.
+- Rework README with a no-database quick try, report output, and safety guarantees.
+
+**Internal refactor (no behavior change)**
+
+- Extract `Logging` module and remove duplicated warning helpers.
+- Extract `TagQuery`, `TagsColumn`, and `TagAccessors` helpers from `LlmApiCall`.
+- Introduce typed `Cost`, `Event`, and `ParsedUsage` value objects while preserving hash-like access.
+- Move storage dispatch into dedicated backend objects with a uniform save contract.
+- Split `Report` into `ReportData` and `ReportFormatter`.
+- Use `OpenaiUsage` composition for OpenAI-compatible providers instead of parser inheritance.
+- Move config enum validation into `Configuration` setters.
+- Memoize the merged built-in/file/override prices table.
+- Restrict the Gemini parser to `generateContent` and `streamGenerateContent` paths.
+
+## [0.1.2] - 2026-04-18
+
+### Added
+
+- Auto-detect OpenRouter and DeepSeek as OpenAI-compatible providers.
+- Add `openai_compatible_providers` configuration for private OpenAI-compatible gateways.
+- Add `BudgetExceededError` and `budget_exceeded_behavior` for best-effort budget guardrails.
+- Add `:raise` and `:block_requests` budget behaviors; `:block_requests` is not a hard cap under concurrency.
+- Add `StorageError` and `storage_error_behavior` so storage failures do not have to break host LLM calls.
+- Add `UnknownPricingError` and `unknown_pricing_behavior` for unknown model pricing.
+- Add built-in `prices.json` registry with metadata and source URLs.
+- Add `prices_file` configuration for local JSON/YAML pricing overrides.
+- Add `with_cost`, `without_cost`, and `unknown_pricing` ActiveRecord scopes.
+- Add `latency_ms` tracking for Faraday calls, manual tracking, notifications, and ActiveRecord storage.
+- Add `with_latency`, `average_latency_ms`, `latency_by_model`, and `latency_by_provider`.
+- Use PostgreSQL `jsonb` storage for tags in newly generated migrations.
+- Add a GIN index on `llm_api_calls.tags` for PostgreSQL installs.
+- Add adapter-aware `by_tag` querying with JSONB containment on PostgreSQL and text fallback elsewhere.
+- Add `by_tags`, `by_user`, and `by_feature` scopes for common attribution queries.
+- Add `llm_cost_tracker:upgrade_tags_to_jsonb` generator for existing PostgreSQL installs.
+- Add `llm_cost_tracker:upgrade_cost_precision` generator for widening stored cost columns.
+- Add `llm_cost_tracker:add_latency_ms` generator for existing installs.
+
+### Changed
+
+- Store tags as a Hash for JSON-backed columns and as JSON text for fallback columns.
+- Keep internal usage metadata such as cache token counts out of stored attribution tags.
+- Normalize provider-prefixed model IDs like `openai/gpt-4o-mini` for built-in price lookup.
+- Normalize configured OpenAI-compatible host keys to lowercase after configuration.
+- Avoid double fuzzy-match passes during price lookup.
+- Widen generated cost decimal columns to `precision: 20, scale: 8`.
+- Count Gemini `thoughtsTokenCount` as output tokens for better thinking-mode cost estimates.
+- Warn when Faraday exposes an unreadable streaming/SSE response body.
+- Document tag storage behavior, budget guardrail limits, known limitations, common tag scopes, and upgrade flows.
+- Clarify that budget errors raised after a response occur after the event has been recorded.
+- Route custom storage exceptions that inherit from `LlmCostTracker::Error` through `storage_error_behavior`.
+
 ## [0.1.1] - 2026-04-17
 
 ### Fixed

data/README.md

@@ -1,12 +1,31 @@
 # LlmCostTracker
 
-**Self-hosted LLM API cost tracking for Ruby and Rails apps.**
+**See where your Rails app spends money on LLM APIs.**
 
-Track token usage and estimated costs for OpenAI, Anthropic, and Google Gemini calls from Faraday-based Ruby clients. Store the data in your own database, tag calls by user or feature, and get budget alerts without adding an external SaaS or proxy.
+Track cost by user, tenant, feature, provider, and model, all in your own database. No proxy. No SaaS required.
 
-[![Gem Version](https://badge.fury.io/rb/llm_cost_tracker.svg)](https://rubygems.org/gems/llm_cost_tracker)
+[![Gem Version](https://img.shields.io/gem/v/llm_cost_tracker.svg)](https://rubygems.org/gems/llm_cost_tracker)
 [![CI](https://github.com/sergey-homenko/llm_cost_tracker/actions/workflows/ruby.yml/badge.svg)](https://github.com/sergey-homenko/llm_cost_tracker/actions)
 
+```text
+LLM Cost Report (last 30 days)
+
+Total cost: $127.420000
+Requests: 4,218
+Avg latency: 812ms
+Unknown pricing: 0
+
+By model:
+  gpt-4o                      $82.100000
+  claude-sonnet-4-6           $31.200000
+  gemini-2.5-flash            $14.120000
+
+By feature:
+  chat                        $73.500000
+  summarizer                  $29.220000
+  translate                   $24.700000
+```
+
 ## Why?
 
 Every Rails app integrating LLMs faces the same problem: **you don't know how much AI is costing you** until the invoice arrives. Full observability platforms like Langfuse and Helicone are powerful, but sometimes you just need a small Rails-native cost ledger that lives in your app database.
@@ -17,7 +36,9 @@ Every Rails app integrating LLMs faces the same problem: **you don't know how mu
 - 🏠 **Self-hosted** — your data stays in your database
 - 🧩 **Client-light** — works with raw Faraday and LLM gems that expose their Faraday connection
 - 🏷️ **Attribution-first** — tag spend by feature, tenant, user, job, or environment
-- 💸 **Budget-aware** — emit notifications and callbacks before spend surprises you
+- 🌐 **OpenAI-compatible** — auto-detect OpenRouter and DeepSeek, with custom compatible hosts configurable
+- 🛑 **Budget guardrails** — notify, raise, or block requests when monthly spend is exhausted
+- 📊 **Quick reports** — print a terminal cost report with one rake task
 
 This gem is intentionally not a tracing platform, prompt CMS, eval system, or gateway. It focuses on the boring but valuable question: "What did this app spend on LLM APIs, and where did that spend come from?"
 
@@ -36,28 +57,41 @@ bin/rails generate llm_cost_tracker:install
 bin/rails db:migrate
 ```
 
-## Quick Start
-
-### Option 1: Faraday Middleware
+## Try It In 30 Seconds
 
-If your LLM client uses Faraday, add the middleware to that connection:
+Try cost calculation without a database or migration:
 
 ```ruby
-conn = Faraday.new(url: "https://api.openai.com") do |f|
-  f.use :llm_cost_tracker, tags: { feature: "chat", user_id: current_user.id }
-  f.request :json
-  f.response :json
-  f.adapter Faraday.default_adapter
+require "llm_cost_tracker"
+
+LlmCostTracker.configure do |config|
+  config.storage_backend = :log
 end
 
-# Every supported LLM request through this connection is tracked
-response = conn.post("/v1/responses", {
-  model: "gpt-5-mini",
-  input: "Hello!"
-})
+LlmCostTracker.track(
+  provider: :openai,
+  model: "gpt-4o",
+  input_tokens: 1000,
+  output_tokens: 200,
+  feature: "demo"
+)
+```
+
+Output:
+
+```text
+[LlmCostTracker] openai/gpt-4o tokens=1000+200 cost=$0.004500 tags={:feature=>"demo"}
 ```
 
-### Option 2: Patch an existing client
+## Quick Start
+
+Use the path that matches your app:
+
+- Using `ruby-openai`, `ruby_llm`, or another client that exposes Faraday? Patch that client's Faraday connection.
+- Using raw Faraday? Add the middleware directly.
+- Using a client without Faraday access? Use manual tracking.
+
+### Option 1: Patch An Existing Client
 
 Some LLM gems expose their Faraday connection. For example, with `ruby-openai`:
 
@@ -67,11 +101,51 @@ OpenAI.configure do |config|
   config.access_token = ENV["OPENAI_API_KEY"]
 
   config.faraday do |f|
-    f.use :llm_cost_tracker, tags: { feature: "openai_default" }
+    f.use :llm_cost_tracker, tags: -> {
+      {
+        user_id: Current.user&.id,
+        feature: Current.llm_feature || "openai"
+      }
+    }
   end
 end
 ```
 
+For Rails apps, `tags:` can be a callable so request-local values are evaluated per request:
+
+```ruby
+# app/models/current.rb
+class Current < ActiveSupport::CurrentAttributes
+  attribute :user, :tenant, :llm_feature
+end
+
+# app/controllers/application_controller.rb
+before_action do
+  Current.user = current_user
+  Current.tenant = current_tenant if respond_to?(:current_tenant, true)
+  Current.llm_feature = "chat"
+end
+```
+
+### Option 2: Faraday Middleware
+
+If your LLM client uses Faraday, add the middleware to that connection:
+
+```ruby
+conn = Faraday.new(url: "https://api.openai.com") do |f|
+  f.use :llm_cost_tracker, tags: -> { { feature: "chat", user_id: Current.user&.id } }
+  f.request :json
+  f.response :json
+  f.adapter Faraday.default_adapter
+end
+
+# Every supported LLM request through this connection is tracked
+response = conn.post("/v1/responses", {
+  model: "gpt-5-mini",
+  input: "Hello!"
+})
+```
+
 If a client does not expose its HTTP connection, use manual tracking or register a custom parser around the HTTP layer you control.
 
 ### Option 3: Manual tracking
@@ -103,6 +177,9 @@ LlmCostTracker.configure do |config|
 
   # Monthly budget in USD
   config.monthly_budget = 500.00
+  config.budget_exceeded_behavior = :notify # :notify, :raise, or :block_requests
+  config.storage_error_behavior = :warn # :ignore, :warn, or :raise
+  config.unknown_pricing_behavior = :warn # :ignore, :warn, or :raise
 
   # Alert callback
   config.on_budget_exceeded = ->(data) {
@@ -113,16 +190,135 @@ LlmCostTracker.configure do |config|
   }
 
   # Override pricing for custom/fine-tuned models (per 1M tokens)
+  config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
   config.pricing_overrides = {
     "ft:gpt-4o-mini:my-org" => { input: 0.30, cached_input: 0.15, output: 1.20 }
   }
+
+  # OpenAI-compatible APIs. OpenRouter and DeepSeek are included by default.
+  config.openai_compatible_providers["llm.my-company.com"] = "internal_gateway"
+end
+```
+
+Pricing is best-effort and based on public provider pricing for standard token usage. Providers change pricing frequently, and some features have extra charges or tiered pricing. OpenRouter-style model IDs such as `openai/gpt-4o-mini` are normalized to built-in model names when possible. Use `prices_file` or `pricing_overrides` for fine-tunes, gateway-specific model IDs, enterprise discounts, batch pricing, long-context premiums, and any model this gem does not know yet.
+
+Storage errors are non-fatal by default:
+
+```ruby
+config.storage_error_behavior = :warn # default
+config.storage_error_behavior = :raise # fail fast with StorageError
+config.storage_error_behavior = :ignore # skip storage failures silently
+```
+
+With the default `:warn` behavior, tracking emits a warning and lets the LLM response continue if ActiveRecord or custom storage fails. `LlmCostTracker::StorageError` exposes `original_error` when `:raise` is enabled.
+
+Unknown model pricing is visible by default:
+
+```ruby
+config.unknown_pricing_behavior = :warn # default
+config.unknown_pricing_behavior = :raise # fail fast with UnknownPricingError
+config.unknown_pricing_behavior = :ignore # keep tracking tokens silently
+```
+
+When pricing is unknown, the event can still be recorded with token counts, but `cost` is `nil` and budget enforcement is skipped for that event. Use `prices_file` or `pricing_overrides` to ensure all production models are priced. Check this ActiveRecord query for a list of unpriced models in your data:
+
+```ruby
+LlmCostTracker::LlmApiCall.unknown_pricing.group(:model).count
+```
+
+### Keeping Prices Current
+
+Built-in prices live in `lib/llm_cost_tracker/prices.json`, with `updated_at`, `unit`, `currency`, and source URLs in the file metadata. The gem does not fetch pricing on boot; that keeps it self-hosted and avoids hidden external dependencies.
+
+For production apps, keep a local JSON or YAML price file and point the gem at it:
+
+```bash
+bin/rails generate llm_cost_tracker:prices
+```
+
+```ruby
+config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
+```
+
+Example JSON:
+
+```json
+{
+  "metadata": {
+    "updated_at": "2026-04-18",
+    "currency": "USD",
+    "unit": "1M tokens"
+  },
+  "models": {
+    "my-gateway/gpt-4o-mini": {
+      "input": 0.20,
+      "cached_input": 0.10,
+      "output": 0.80
+    }
+  }
+}
+```
+
+`pricing_overrides` still has the highest precedence, so you can use it for small Ruby-only overrides and keep broader provider tables in the file. A practical release rhythm is to refresh built-in `prices.json` quarterly and use `prices_file` for urgent provider changes between gem releases.
+
+## Budget Enforcement
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.storage_backend = :active_record
+  config.monthly_budget = 100.00
+  config.budget_exceeded_behavior = :block_requests
+end
+```
+
+Budget behavior options:
+
+- `:notify` — default. Calls `on_budget_exceeded` after a tracked event pushes the month over budget.
+- `:raise` — records the event, then raises `LlmCostTracker::BudgetExceededError` when the month is over budget.
+- `:block_requests` — blocks Faraday LLM requests before the HTTP call when the ActiveRecord monthly total has already reached the budget. If a request pushes the month over budget, it also raises after recording the event.
+
+`BudgetExceededError` exposes `monthly_total`, `budget`, and `last_event`:
+
+```ruby
+begin
+  client.chat(...)
+rescue LlmCostTracker::BudgetExceededError => e
+  Rails.logger.warn("LLM budget exhausted: #{e.monthly_total} / #{e.budget}")
 end
 ```
 
-Pricing is best-effort and based on public provider pricing for standard token usage. Providers change pricing frequently, and some features have extra charges or tiered pricing. Use `pricing_overrides` for fine-tunes, gateway-specific model IDs, enterprise discounts, batch pricing, long-context premiums, and any model this gem does not know yet.
+Pre-request blocking needs `storage_backend = :active_record` because the middleware must query your stored monthly total before sending the request. With `:log` or `:custom` storage, `:raise` and the post-response part of `:block_requests` still work for the event being tracked.
+
+`:block_requests` is a best-effort guardrail, not a transactional hard quota. In highly concurrent deployments, multiple workers can pass the preflight check at the same time before any of them records its final cost. The request that first pushes the month over budget is stored before the post-response `BudgetExceededError` is raised; later Faraday requests are blocked during preflight once the stored monthly total is exhausted. Use provider-side limits or a gateway-level quota if you need strict cross-process enforcement.
 
 ## Querying Costs (ActiveRecord)
 
+Print a quick terminal report:
+
+```bash
+bin/rails llm_cost_tracker:report
+
+# Optional: change the window
+DAYS=7 bin/rails llm_cost_tracker:report
+```
+
+Example:
+
+```text
+LLM Cost Report (last 30 days)
+
+Total cost: $127.420000
+Requests: 4,218
+Avg latency: 812ms
+Unknown pricing: 0
+
+By provider:
+  openai                      $96.220000
+  anthropic                   $31.200000
+```
+
+Or query the ledger directly:
+
 ```ruby
 # Today's total spend
 LlmCostTracker::LlmApiCall.today.total_cost
@@ -140,16 +336,65 @@ LlmCostTracker::LlmApiCall.this_month.cost_by_provider
 LlmCostTracker::LlmApiCall.daily_costs(days: 7)
 # => { "2026-04-10" => 1.5, "2026-04-11" => 2.3, ... }
 
+# Latency overview
+LlmCostTracker::LlmApiCall.with_latency.average_latency_ms
+LlmCostTracker::LlmApiCall.this_month.latency_by_model
+
 # Filter by feature
 LlmCostTracker::LlmApiCall.by_tag("feature", "chat").this_month.total_cost
 
 # Filter by user
 LlmCostTracker::LlmApiCall.by_tag("user_id", "42").today.total_cost
+LlmCostTracker::LlmApiCall.by_user(42).today.total_cost
+
+# Filter by multiple tags
+LlmCostTracker::LlmApiCall.by_tags(user_id: 42, feature: "chat").this_month.total_cost
+
+# Feature shortcut
+LlmCostTracker::LlmApiCall.by_feature("summarizer").this_month.total_cost
+
+# Find models without pricing
+LlmCostTracker::LlmApiCall.unknown_pricing.group(:model).count
+LlmCostTracker::LlmApiCall.with_cost.this_month.total_cost
 
 # Custom date range
 LlmCostTracker::LlmApiCall.between(1.week.ago, Time.current).cost_by_model
 ```
 
+### Tag Storage
+
+The install generator uses `jsonb` tags with a GIN index on PostgreSQL:
+
+```ruby
+t.jsonb :tags, null: false, default: {}
+add_index :llm_api_calls, :tags, using: :gin
+```
+
+On SQLite, MySQL, and other adapters, tags fall back to JSON stored in a text column. The `by_tag` scope automatically uses PostgreSQL JSONB containment when the column supports it, and the text fallback otherwise. This works, but tag queries are less efficient than PostgreSQL JSONB containment.
+
+If you installed `llm_cost_tracker` before JSONB tags were available and your app uses PostgreSQL, generate an upgrade migration:
+
+```bash
+bin/rails generate llm_cost_tracker:upgrade_tags_to_jsonb
+bin/rails db:migrate
+```
+
+This converts the existing `tags` text column to `jsonb`, keeps existing tag data, and adds the GIN index.
+
+If you installed an earlier version with `precision: 12, scale: 8` cost columns, widen them for larger production ledgers:
+
+```bash
+bin/rails generate llm_cost_tracker:upgrade_cost_precision
+bin/rails db:migrate
+```
+
+If you installed before `latency_ms` was available, add the latency column:
+
+```bash
+bin/rails generate llm_cost_tracker:add_latency_ms
+bin/rails db:migrate
+```
+
 ## ActiveSupport::Notifications
 
 Every tracked call emits an `llm_request.llm_cost_tracker` event:
@@ -163,6 +408,7 @@ ActiveSupport::Notifications.subscribe("llm_request.llm_cost_tracker") do |*, pa
   #   input_tokens: 150,
   #   output_tokens: 42,
   #   total_tokens: 192,
+  #   latency_ms: 248,
   #   cost: {
   #     input_cost: 0.000375,
   #     cached_input_cost: 0.0,
@@ -188,19 +434,72 @@ LlmCostTracker.configure do |config|
   config.storage_backend = :custom
   config.custom_storage = ->(event) {
     InfluxDB.write("llm_costs", {
-      values: { cost: event[:cost][:total_cost], tokens: event[:total_tokens] },
+      values: {
+        cost: event[:cost]&.fetch(:total_cost, nil),
+        tokens: event[:total_tokens],
+        latency_ms: event[:latency_ms]
+      },
       tags: { provider: event[:provider], model: event[:model] }
     })
   }
 end
 ```
 
+## OpenAI-Compatible Providers
+
+```ruby
+LlmCostTracker.configure do |config|
+  # Built in:
+  # "openrouter.ai" => "openrouter"
+  # "api.deepseek.com" => "deepseek"
+  config.openai_compatible_providers["gateway.example.com"] = "internal_gateway"
+end
+```
+
+Any configured host is parsed with the OpenAI-compatible usage shape:
+
+- `prompt_tokens` / `completion_tokens` / `total_tokens`
+- `input_tokens` / `output_tokens` / `total_tokens`
+- optional cached input details when the response includes them
+
+This covers OpenRouter, DeepSeek, and private gateways that expose OpenAI-style Chat Completions, Responses, Completions, or Embeddings endpoints.
+
+## Safety Guarantees
+
+- `llm_cost_tracker` does not make external HTTP calls.
+- It does not store prompt or response bodies.
+- Faraday responses are not modified.
+- Storage failures are non-fatal by default via `storage_error_behavior = :warn`.
+- Budget and unknown-pricing errors are raised only when you opt into `:raise` or `:block_requests`.
+- Pricing is local and best-effort; use `prices_file` or `pricing_overrides` for production-specific rates.
+- Streaming/SSE calls are skipped with a warning when the final usage payload is not readable by Faraday.
+
+## Production Checklist
+
+- Use `storage_backend = :active_record` in production.
+- Set `monthly_budget` and choose `budget_exceeded_behavior`.
+- Treat `:block_requests` as best-effort in concurrent systems, not a strict quota.
+- Keep `unknown_pricing_behavior = :warn` or `:raise` until pricing overrides are complete.
+- Add `pricing_overrides` for custom, fine-tuned, gateway-specific, or newly released models.
+- Tag calls with `tenant_id`, `user_id`, and `feature` where possible.
+- Check `LlmCostTracker::LlmApiCall.unknown_pricing.group(:model).count` after deploys.
+- Track `latency_ms` and watch `latency_by_model` for slow or degraded providers.
+
+## Known Limitations
+
+- `:block_requests` is best-effort under concurrency. For hard caps, use an external quota system, provider-side limits, or a gateway-level budget.
+- Streaming/SSE calls are tracked only when Faraday exposes a final response body with usage data. Otherwise the gem warns and skips automatic tracking.
+- Anthropic cache creation TTL variants are not modeled separately yet; 1-hour cache writes may be underestimated compared with the default 5-minute cache write rate.
+- OpenAI reasoning tokens are included in output-token totals when providers report them that way, but separate reasoning-token attribution is not stored yet.
+
 ## Adding a Custom Provider Parser
 
+Use this for providers that are not OpenAI-compatible and return a different usage shape.
+
 ```ruby
-class DeepSeekParser < LlmCostTracker::Parsers::Base
+class AcmeParser < LlmCostTracker::Parsers::Base
   def match?(url)
-    url.to_s.include?("api.deepseek.com")
+    url.to_s.include?("api.acme-llm.example")
   end
 
   def parse(request_url, request_body, response_status, response_body)
@@ -211,16 +510,16 @@ class DeepSeekParser < LlmCostTracker::Parsers::Base
     return nil unless usage
 
     {
-      provider: "deepseek",
+      provider: "acme",
       model: response["model"],
-      input_tokens: usage["prompt_tokens"] || 0,
-      output_tokens: usage["completion_tokens"] || 0
+      input_tokens: usage["input"] || 0,
+      output_tokens: usage["output"] || 0
     }
   end
 end
 
 # Register it
-LlmCostTracker::Parsers::Registry.register(DeepSeekParser.new)
+LlmCostTracker::Parsers::Registry.register(AcmeParser.new)
 ```
 
 ## Supported Providers
@@ -228,6 +527,9 @@ LlmCostTracker::Parsers::Registry.register(DeepSeekParser.new)
 | Provider | Auto-detected | Models with pricing |
 |----------|:---:|---|
 | OpenAI | ✅ | GPT-5.2/5.1/5, GPT-5 mini/nano, GPT-4.1, GPT-4o, o1/o3/o4-mini |
+| OpenRouter | ✅ | Uses OpenAI-compatible usage; provider-prefixed OpenAI model IDs are normalized when possible |
+| DeepSeek | ✅ | Uses OpenAI-compatible usage; add `pricing_overrides` for DeepSeek model pricing |
+| OpenAI-compatible hosts | 🔧 | Configure `openai_compatible_providers` |
 | Anthropic | ✅ | Claude Opus 4.6/4.1/4, Sonnet 4.6/4.5/4, Haiku 4.5, Claude 3.x |
 | Google Gemini | ✅ | Gemini 2.5 Pro/Flash/Flash-Lite, 2.0 Flash/Flash-Lite, 1.5 Pro/Flash |
 | Any other | 🔧 | Via custom parser (see above) |
@@ -235,6 +537,7 @@ LlmCostTracker::Parsers::Registry.register(DeepSeekParser.new)
 Supported endpoint families:
 
 - OpenAI: Chat Completions, Responses, Completions, Embeddings
+- OpenAI-compatible: Chat Completions, Responses, Completions, Embeddings
 - Anthropic: Messages
 - Google Gemini: `generateContent` responses with `usageMetadata`
 
@@ -251,9 +554,9 @@ Your App → Faraday → [LlmCostTracker Middleware] → LLM API
                ActiveRecord / Log / Custom
 ```
 
-The middleware intercepts **outgoing** HTTP responses (not incoming Rails requests), parses the provider usage object, looks up pricing, and records the event. It never modifies requests or responses.
+The middleware intercepts **outgoing** HTTP responses (not incoming Rails requests), parses the provider usage object, looks up pricing, and records the event. It never modifies requests or responses. Put `llm_cost_tracker` inside the Faraday stack where it can see the final response body; if another middleware consumes or transforms streaming bodies, use manual tracking.
 
-For streaming APIs, tracking depends on the final response body including provider usage data. If the client consumes server-sent events without exposing the final usage payload to Faraday, use manual tracking.
+For streaming APIs, tracking depends on the final response body including provider usage data. If the client consumes server-sent events without exposing the final usage payload to Faraday, the gem logs a warning and skips tracking; use manual tracking for those calls.
 
 ## Development
 

data/lib/llm_cost_tracker/budget.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "logging"
+
+module LlmCostTracker
+  class Budget
+    WARNING_MUTEX = Mutex.new
+    private_constant :WARNING_MUTEX
+
+    class << self
+      def enforce!
+        return unless LlmCostTracker.configuration.monthly_budget
+        return unless behavior == :block_requests
+        return warn_non_active_record_block_requests unless LlmCostTracker.configuration.active_record?
+
+        monthly_total = calculate_monthly_total(0)
+        return unless monthly_total >= LlmCostTracker.configuration.monthly_budget
+
+        handle_exceeded(monthly_total: monthly_total)
+      end
+
+      def check!(event)
+        config = LlmCostTracker.configuration
+        return unless config.monthly_budget
+        return unless event[:cost]
+
+        monthly_total = calculate_monthly_total(event[:cost][:total_cost])
+        return unless monthly_total > config.monthly_budget
+
+        handle_exceeded(monthly_total: monthly_total, last_event: event)
+      end
+
+      private
+
+      def calculate_monthly_total(latest_cost)
+        if LlmCostTracker.configuration.active_record?
+          active_record_monthly_total
+        else
+          latest_cost
+        end
+      end
+
+      def active_record_monthly_total
+        require_relative "llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
+        require_relative "storage/active_record_store" unless defined?(LlmCostTracker::Storage::ActiveRecordStore)
+
+        LlmCostTracker::Storage::ActiveRecordStore.monthly_total
+      rescue LoadError => e
+        raise Error, "ActiveRecord storage requires the active_record gem: #{e.message}"
+      end
+
+      def warn_non_active_record_block_requests
+        should_warn = WARNING_MUTEX.synchronize do
+          unless @warned_non_active_record_block_requests
+            @warned_non_active_record_block_requests = true
+            true
+          end
+        end
+        return unless should_warn
+
+        Logging.warn(":block_requests preflight requires storage_backend = :active_record; request was not blocked.")
+      end
+
+      def handle_exceeded(monthly_total:, last_event: nil)
+        config = LlmCostTracker.configuration
+        payload = {
+          monthly_total: monthly_total,
+          budget: config.monthly_budget,
+          last_event: last_event
+        }
+
+        config.on_budget_exceeded&.call(payload)
+        raise BudgetExceededError.new(**payload) if raise_on_exceeded?
+      end
+
+      def raise_on_exceeded?
+        %i[raise block_requests].include?(behavior)
+      end
+
+      def behavior
+        LlmCostTracker.configuration.budget_exceeded_behavior
+      end
+    end
+  end
+end