llm_cost_tracker 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7b40f1010c79358da89ffdd10637f59fa90e24aa0f50aec364828d2e2cbf5b9
-  data.tar.gz: d12d1cf407b87afd6e1084c22ceda143c7ab9bf5e6ea6825d70a8e24969cafa5
+  metadata.gz: 6a014d7c3de26b91ba6a0b99d300a803d04ab8a95c55b374377d6b8cdf631e50
+  data.tar.gz: 7e042cf740a65c1019d0ee986eeec9fc2266a1ec59c55d4807f306521f95f869
 SHA512:
-  metadata.gz: 949157f0a6718bc03f8f0d825982ed732df2754ddf1e4ee07b18522b0e20cc4367a97c599071bcda95bbdda4dde0e160f5d586a9b42a0dd8b1f3c89910286547
-  data.tar.gz: 9ea9007142d157446271bcf81bc4786e4b22a00f6e353dc2e3dc26c1be12d9abf88aed8d8852da37778b5fe3f71fcd4422c6153d8a531f195adaf0d0b9bb8dd2
+  metadata.gz: 1c41d7a9002fb484df80b6d3e5c7ce1fc14a3d481443f0bbefe1c74a4e2a0f92a039f56677a7a354dbfaeaaae6b5d4727bb5ca9466b06b77d574d26efd477fdb
+  data.tar.gz: d8017bbf7975f5bafbc4328dc8df76a614bc5e7700bb14569cead5ffc06aac6a4828707a9a609b9b7af69e4b7e3a08543712a750ed79d7b125ab2c96336cefa1

data/CHANGELOG.md

@@ -5,6 +5,43 @@ 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

data/README.md

@@ -2,7 +2,7 @@
 
 **Self-hosted LLM API cost tracking for Ruby and Rails apps.**
 
-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, 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)
@@ -17,6 +17,8 @@ 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
+- 🌐 **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?"
@@ -103,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) {
@@ -113,13 +118,102 @@ 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, 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. 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.
+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)
 
@@ -140,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:
@@ -163,6 +306,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 +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)
@@ -211,16 +398,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 +415,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 +425,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 +442,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,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

data/lib/llm_cost_tracker/configuration.rb

@@ -2,15 +2,31 @@
 
 module LlmCostTracker
   class Configuration
+    # Hostname => provider name for OpenAI-compatible APIs.
+    OPENAI_COMPATIBLE_PROVIDERS = {
+      "openrouter.ai" => "openrouter",
+      "api.deepseek.com" => "deepseek"
+    }.freeze
+
+    BUDGET_EXCEEDED_BEHAVIORS = %i[notify raise block_requests].freeze
+    STORAGE_ERROR_BEHAVIORS = %i[ignore warn raise].freeze
+    UNKNOWN_PRICING_BEHAVIORS = %i[ignore warn raise].freeze
+
     attr_accessor :enabled,
                   :storage_backend,    # :log, :active_record, :custom
                   :custom_storage,     # callable object for :custom backend
                   :default_tags,       # Hash of default tags added to every event
                   :on_budget_exceeded, # callable, receives event hash
                   :monthly_budget,     # Float, in USD — nil means no limit
+                  :budget_exceeded_behavior, # :notify, :raise, :block_requests
+                  :storage_error_behavior, # :ignore, :warn, :raise
+                  :unknown_pricing_behavior, # :ignore, :warn, :raise
                   :log_level,          # :debug, :info, :warn
+                  :prices_file,        # JSON/YAML file that overrides built-in prices
                   :pricing_overrides   # Hash to override built-in pricing
 
+    attr_reader :openai_compatible_providers
+
     def initialize
       @enabled            = true
       @storage_backend    = :log
@@ -18,8 +34,21 @@ module LlmCostTracker
       @default_tags       = {}
       @on_budget_exceeded = nil
       @monthly_budget     = nil
+      @budget_exceeded_behavior = :notify
+      @storage_error_behavior = :warn
+      @unknown_pricing_behavior = :warn
       @log_level          = :info
+      @prices_file        = nil
       @pricing_overrides  = {}
+      self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
+    end
+
+    def openai_compatible_providers=(providers)
+      @openai_compatible_providers = normalize_openai_compatible_providers(providers)
+    end
+
+    def normalize_openai_compatible_providers!
+      self.openai_compatible_providers = openai_compatible_providers
     end
 
     def active_record?
@@ -29,5 +58,13 @@ module LlmCostTracker
     def log?
       storage_backend == :log
     end
+
+    private
+
+    def normalize_openai_compatible_providers(providers)
+      (providers || {}).each_with_object({}) do |(host, provider), normalized|
+        normalized[host.to_s.downcase] = provider.to_s
+      end
+    end
   end
 end

data/lib/llm_cost_tracker/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  class Error < StandardError; end
+
+  class BudgetExceededError < Error
+    attr_reader :monthly_total, :budget, :last_event
+
+    def initialize(monthly_total:, budget:, last_event: nil)
+      @monthly_total = monthly_total
+      @budget = budget
+      @last_event = last_event
+
+      super("LLM monthly budget exceeded: $#{format('%.6f', monthly_total)} / $#{format('%.6f', budget)}")
+    end
+  end
+
+  class UnknownPricingError < Error
+    attr_reader :model
+
+    def initialize(model:)
+      @model = model
+
+      super("No pricing configured for LLM model: #{model.inspect}")
+    end
+  end
+
+  class StorageError < Error
+    attr_reader :original_error
+
+    def initialize(original_error)
+      @original_error = original_error
+
+      super("Failed to store LLM cost event: #{original_error.class}: #{original_error.message}")
+    end
+  end
+end

data/lib/llm_cost_tracker/event_metadata.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module EventMetadata
+    INTERNAL_TAG_KEYS = %w[
+      cache_creation_input_tokens
+      cache_creation_tokens
+      cache_read_input_tokens
+      cache_read_tokens
+      cached_input_tokens
+      input_tokens
+      output_tokens
+      reasoning_tokens
+      total_tokens
+    ].freeze
+
+    class << self
+      def usage_data(input_tokens, output_tokens, metadata)
+        cache_read_input_tokens = integer_metadata(metadata, :cache_read_input_tokens, :cache_read_tokens)
+        cache_creation_input_tokens = integer_metadata(
+          metadata,
+          :cache_creation_input_tokens,
+          :cache_creation_tokens
+        )
+        cached_input_tokens = integer_metadata(metadata, :cached_input_tokens)
+
+        {
+          input_tokens: input_tokens.to_i,
+          output_tokens: output_tokens.to_i,
+          cached_input_tokens: cached_input_tokens,
+          cache_read_input_tokens: cache_read_input_tokens,
+          cache_creation_input_tokens: cache_creation_input_tokens,
+          total_tokens: input_tokens.to_i + output_tokens.to_i +
+            cache_read_input_tokens + cache_creation_input_tokens
+        }
+      end
+
+      def tags(metadata)
+        metadata.reject { |key, _value| INTERNAL_TAG_KEYS.include?(key.to_s) }
+      end
+
+      private
+
+      def integer_metadata(metadata, *keys)
+        keys.each do |key|
+          value = metadata[key] || metadata[key.to_s]
+          return value.to_i unless value.nil?
+        end
+
+        0
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/add_latency_ms_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LlmCostTracker
+  module Generators
+    class AddLatencyMsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration to add llm_api_calls.latency_ms"
+
+      def create_migration_file
+        migration_template(
+          "add_latency_ms_to_llm_api_calls.rb.erb",
+          "db/migrate/add_latency_ms_to_llm_api_calls.rb"
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_latency_ms_to_llm_api_calls.rb.erb

@@ -0,0 +1,9 @@
+class AddLatencyMsToLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :llm_api_calls, :latency_ms, :integer unless column_exists?(:llm_api_calls, :latency_ms)
+  end
+
+  def down
+    remove_column :llm_api_calls, :latency_ms if column_exists?(:llm_api_calls, :latency_ms)
+  end
+end