llm_cost_tracker 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16c6c4c230300b2caebc69e1f0aeb9a7af232278a6e77401aba0d490bb16b4a2
-  data.tar.gz: 4b32fb25d22c645e4d66767264130bc44ce730e553636cefca8e4884dede7b94
+  metadata.gz: 6a014d7c3de26b91ba6a0b99d300a803d04ab8a95c55b374377d6b8cdf631e50
+  data.tar.gz: 7e042cf740a65c1019d0ee986eeec9fc2266a1ec59c55d4807f306521f95f869
 SHA512:
-  metadata.gz: f403ebeeb6a98164bc2318b9f3b8f49e03750fd5c5d328ac0b0f3c0557f16c39d8f247aa663bdd15b605df779be7d4b4db7445fb79d10eb4c89ef17a687a77d7
-  data.tar.gz: fd04a24708901e998127d6582290da90b35f62f7a36d794805a4677656be9191eed14235b634b72924ac4178837aa9dbace3a57fde18829d47b6a8208e295af2
+  metadata.gz: 1c41d7a9002fb484df80b6d3e5c7ce1fc14a3d481443f0bbefe1c74a4e2a0f92a039f56677a7a354dbfaeaaae6b5d4727bb5ca9466b06b77d574d26efd477fdb
+  data.tar.gz: d8017bbf7975f5bafbc4328dc8df76a614bc5e7700bb14569cead5ffc06aac6a4828707a9a609b9b7af69e4b7e3a08543712a750ed79d7b125ab2c96336cefa1

data/.rubocop.yml

@@ -0,0 +1,44 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+  UseCache: false
+  Exclude:
+    - "tmp/**/*"
+    - "vendor/**/*"
+    - "pkg/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Metrics/BlockLength:
+  Exclude:
+    - "*.gemspec"
+    - "spec/**/*.rb"
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 45
+
+Metrics/ClassLength:
+  Max: 130
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/ParameterLists:
+  Max: 6
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Layout/HashAlignment:
+  Enabled: false

data/CHANGELOG.md

@@ -5,6 +5,68 @@ 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.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
+
+- Lazy-load ActiveRecord storage so `storage_backend = :active_record` persists events reliably.
+- Avoid double-counting the latest ActiveRecord event in monthly budget callbacks.
+- Track OpenAI Responses API usage via `/v1/responses`.
+- Parse OpenAI cached input token details for cache-aware cost estimates.
+- Parse Anthropic cache read and cache creation token usage under canonical metadata keys.
+- Parse Gemini cached content token usage when present.
+- Store ActiveRecord tag values as strings so `by_tag("user_id", "42")` works for numeric IDs.
+
+### Changed
+
+- Refresh built-in pricing for current OpenAI, Anthropic, and Gemini models.
+- Add cache-aware cost calculation fields for cached input, cache reads, and cache creation.
+- Tighten OpenAI URL matching to supported endpoint families only.
+- Reposition README around self-hosted Rails/Ruby cost tracking for Faraday-based clients.
+
+### Added
+
+- Add ActiveRecord integration specs for persistence, tag querying, and budget callbacks.
+- Add RuboCop configuration, rake task, and CI lint step.
+- Require MFA metadata for RubyGems publishing.
+
 ## [0.1.0] - 2026-04-16
 
 ### Added

data/README.md

@@ -1,21 +1,27 @@
 # LlmCostTracker
 
-**Provider-agnostic LLM API cost tracking for Ruby.**
+**Self-hosted LLM API cost tracking for Ruby and Rails apps.**
 
-Track token usage and costs for every LLM API call your app makes — OpenAI, Anthropic, Google Gemini, and any OpenAI-compatible provider. Works as Faraday middleware, so it plugs into **any** Ruby LLM client without code changes.
+Track, attribute, and enforce AI costs for OpenAI, Anthropic, Google Gemini, OpenRouter, DeepSeek, and OpenAI-compatible 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.
 
 [![Gem Version](https://badge.fury.io/rb/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)
 
 ## Why?
 
-Every Rails app integrating LLMs faces the same problem: **you don't know how much AI is costing you** until the invoice arrives. Existing solutions either lock you into a specific LLM gem (like `ruby_llm-monitoring`) or require external SaaS (Langfuse, Helicone).
+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.
 
 `llm_cost_tracker` takes a different approach:
 
-- 🔌 **Provider-agnostic** — intercepts HTTP responses at the Faraday level
+- 🔌 **Faraday-native** — intercepts LLM HTTP responses without changing the response
 - 🏠 **Self-hosted** — your data stays in your database
-- 🧩 **Zero coupling** — works with `ruby-openai`, `anthropic-rb`, `ruby_llm`, or raw Faraday
-- ⚡ **Zero config** — add the middleware, done
+- 🧩 **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
+- 🌐 **OpenAI-compatible** — auto-detect OpenRouter and DeepSeek, with custom compatible hosts configurable
+- 🛑 **Budget guardrails** — notify, raise, or block requests when monthly spend is exhausted
+- 💸 **Budget-aware** — emit notifications and callbacks before spend surprises you
+
+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?"
 
 ## Installation
 
@@ -34,9 +40,9 @@ bin/rails db:migrate
 
 ## Quick Start
 
-### Option 1: Faraday Middleware (automatic)
+### Option 1: Faraday Middleware
 
-If your LLM client uses Faraday (most do), just add the middleware:
+If your LLM client uses Faraday, add the middleware to that connection:
 
 ```ruby
 conn = Faraday.new(url: "https://api.openai.com") do |f|
@@ -46,16 +52,16 @@ conn = Faraday.new(url: "https://api.openai.com") do |f|
   f.adapter Faraday.default_adapter
 end
 
-# Every request through this connection is now tracked automatically
-response = conn.post("/v1/chat/completions", {
-  model: "gpt-4o",
-  messages: [{ role: "user", content: "Hello!" }]
+# Every supported LLM request through this connection is tracked
+response = conn.post("/v1/responses", {
+  model: "gpt-5-mini",
+  input: "Hello!"
 })
 ```
 
 ### Option 2: Patch an existing client
 
-Most LLM gems expose their Faraday connection. For example, with `ruby-openai`:
+Some LLM gems expose their Faraday connection. For example, with `ruby-openai`:
 
 ```ruby
 # config/initializers/openai.rb
@@ -68,6 +74,8 @@ OpenAI.configure do |config|
 end
 ```
 
+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
 
 For non-Faraday clients, track manually:
@@ -78,6 +86,7 @@ LlmCostTracker.track(
   model: "claude-sonnet-4-6",
   input_tokens: 1500,
   output_tokens: 320,
+  cache_read_input_tokens: 1200,
   feature: "summarizer",
   user_id: current_user.id
 )
@@ -96,6 +105,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) {
@@ -106,12 +118,103 @@ 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.json")
   config.pricing_overrides = {
-    "ft:gpt-4o-mini:my-org" => { input: 0.30, output: 1.20 }
+    "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 this ActiveRecord query to find the gaps:
+
+```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:
+
+```ruby
+config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.json")
+```
+
+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
+```
+
+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)
 
 ```ruby
@@ -131,16 +234,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 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.
+
+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:
@@ -154,7 +306,16 @@ ActiveSupport::Notifications.subscribe("llm_request.llm_cost_tracker") do |*, pa
   #   input_tokens: 150,
   #   output_tokens: 42,
   #   total_tokens: 192,
-  #   cost: { input_cost: 0.000375, output_cost: 0.00042, total_cost: 0.000795, currency: "USD" },
+  #   latency_ms: 248,
+  #   cost: {
+  #     input_cost: 0.000375,
+  #     cached_input_cost: 0.0,
+  #     cache_read_input_cost: 0.0,
+  #     cache_creation_input_cost: 0.0,
+  #     output_cost: 0.00042,
+  #     total_cost: 0.000795,
+  #     currency: "USD"
+  #   },
   #   tags: { feature: "chat", user_id: 42 },
   #   tracked_at: 2026-04-16 14:30:00 UTC
   # }
@@ -171,19 +332,62 @@ 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.
+
+## 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)
@@ -194,27 +398,37 @@ 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
 
 | Provider | Auto-detected | Models with pricing |
 |----------|:---:|---|
-| OpenAI | ✅ | GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-4, GPT-3.5-turbo, o1, o1-mini, o3-mini |
-| Anthropic | ✅ | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5, Claude 3.5 Sonnet, Claude 3 Opus |
-| Google Gemini | ✅ | Gemini 2.5 Pro/Flash, 2.0 Flash, 1.5 Pro/Flash |
+| 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) |
 
+Supported endpoint families:
+
+- OpenAI: Chat Completions, Responses, Completions, Embeddings
+- OpenAI-compatible: Chat Completions, Responses, Completions, Embeddings
+- Anthropic: Messages
+- Google Gemini: `generateContent` responses with `usageMetadata`
+
 ## How It Works
 
 ```
@@ -228,7 +442,9 @@ Your App → Faraday → [LlmCostTracker Middleware] → LLM API
                ActiveRecord / Log / Custom
 ```
 
-The middleware intercepts **outgoing** HTTP responses (not incoming requests), parses the `usage` object from the LLM provider's response body, looks up pricing, and records the event. It never modifies requests or responses — it's read-only.
+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, the gem logs a warning and skips tracking; use manual tracking for those calls.
 
 ## Development
 
@@ -237,6 +453,7 @@ git clone https://github.com/sergey-homenko/llm_cost_tracker.git
 cd llm_cost_tracker
 bundle install
 bundle exec rspec
+bundle exec rubocop
 ```
 
 ## Contributing

data/Rakefile

@@ -2,7 +2,9 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "rubocop/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
 
-task default: :spec
+task default: %i[spec rubocop]

data/lib/llm_cost_tracker/budget.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  class Budget
+    class << self
+      WARNING_MUTEX = Mutex.new
+
+      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
+
+        log_warning(":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
+        behavior = (LlmCostTracker.configuration.budget_exceeded_behavior || :notify).to_sym
+        return behavior if Configuration::BUDGET_EXCEEDED_BEHAVIORS.include?(behavior)
+
+        raise Error,
+              "Unknown budget_exceeded_behavior: #{behavior.inspect}. " \
+              "Use one of: #{Configuration::BUDGET_EXCEEDED_BEHAVIORS.join(', ')}"
+      end
+
+      def log_warning(message)
+        message = "[LlmCostTracker] #{message}"
+
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.warn(message)
+        else
+          warn message
+        end
+      end
+    end
+  end
+end