llm_cost_tracker 0.5.2 → 0.5.3

data/docs/streaming.md

@@ -0,0 +1,70 @@
+# Streaming Capture
+
+Streaming calls should appear in the ledger instead of disappearing into a live
+callback. LLM Cost Tracker records them when the provider emits final usage or
+when the app supplies explicit totals.
+
+The full streaming reference is moving here from the README: Faraday streaming,
+`track_stream`, provider response IDs, final usage events, and data-quality
+states.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Capturing calls](../README.md#capturing-calls)
+- [Known limitations](../README.md#known-limitations)
+- [Cookbook](cookbook.md)
+
+## Faraday Path
+
+The middleware tees Faraday's `on_data` callback, keeps chunks flowing to the
+caller, and records usage when the response completes.
+
+OpenAI streams need final usage:
+
+```ruby
+stream_options: { include_usage: true }
+```
+
+Anthropic and Gemini are parsed from their provider stream event shapes when
+usage is present.
+
+## SDK Path
+
+Official OpenAI and Anthropic SDK streams are captured when `config.instrument`
+is enabled for the provider. The returned stream object is preserved, and usage
+is recorded after the stream is consumed.
+
+```ruby
+config.instrument :openai
+config.instrument :anthropic
+```
+
+Captured SDK helpers:
+
+- OpenAI `responses.stream`, `responses.stream_raw`, `responses.retrieve_streaming`, and `chat.completions.stream_raw`.
+- Anthropic `messages.stream` and `messages.stream_raw`.
+
+OpenAI Chat Completions streams need final usage:
+
+```ruby
+stream_options: { include_usage: true }
+```
+
+## Manual Path
+
+```ruby
+LlmCostTracker.track_stream(provider: "openai", model: "gpt-4o") do |stream|
+  my_client.stream(...) { |event| stream.event(event.to_h) }
+end
+```
+
+If the client already knows totals, skip provider event parsing:
+
+```ruby
+stream.usage(input_tokens: 120, output_tokens: 45)
+```
+
+Missing final usage is stored with `usage_source: "unknown"` so the Data Quality
+page can surface it.

data/docs/technical/README.md

@@ -0,0 +1,10 @@
+# Technical Documentation
+
+These files describe the internal module boundaries for LLM Cost Tracker.
+
+- [Module map](module-map.md)
+- [Data flow](data-flow.md)
+- [Extension points](extension-points.md)
+- [Operational notes](operational-notes.md)
+
+The main rule is simple: provider-specific API shapes stop at ingestion boundaries. The ledger, storage, budgets, dashboard, and reports work with canonical billing concepts.

data/docs/technical/data-flow.md

@@ -0,0 +1,67 @@
+# Data Flow
+
+This is the normal path from an application LLM call to stored ledger data.
+
+## Faraday Requests
+
+1. The host app sends an HTTP request through Faraday.
+2. `LlmCostTracker::Middleware::Faraday` checks whether a parser matches the request URL.
+3. For non-streaming responses, the middleware passes request and response data to the parser.
+4. For streaming responses, the middleware tees `on_data`, collects stream events, and parses final usage when the stream completes.
+5. The parser returns `ParsedUsage` with canonical fields.
+6. `Tracker.record` prices and persists the event.
+
+## SDK Integrations
+
+1. The host app enables an integration with `config.instrument`.
+2. `LlmCostTracker::Integrations` checks the SDK version, target classes, and target methods once at install time.
+3. `LlmCostTracker::Integrations` prepends a narrow wrapper to supported SDK resource methods.
+4. The host app keeps calling the provider SDK normally.
+5. The wrapper measures latency, extracts usage from the SDK response object, and sends canonical fields to `Tracker.record`.
+6. If an explicitly enabled SDK is not loaded or does not satisfy the install contract, boot raises before the app silently misses usage.
+
+## Explicit Tracking
+
+1. The host app calls `LlmCostTracker.track` with known usage totals, or `LlmCostTracker.track_stream` with stream events.
+2. `track` sends manual totals directly to `Tracker.record`.
+3. `track_stream` uses `StreamCollector`, then parser lookup by provider when events need parsing.
+4. `Tracker.record` prices and persists the event.
+
+## Canonical Event Build
+
+`Tracker.record` performs the central normalization step:
+
+1. Blank model identifiers become `unknown`.
+2. Input, output, cache-read, cache-write, hidden-output, and pricing-mode values are extracted from metadata.
+3. `Pricing.cost_for` calculates a `Cost` object or returns `nil` for unknown pricing.
+4. Tags are merged from `with_tags`, `default_tags`, middleware tags, and explicit metadata.
+5. An `Event` is created and emitted through `ActiveSupport::Notifications`.
+6. The configured storage backend receives the event.
+7. Budget checks run unless storage explicitly returns `false`.
+
+## ActiveRecord Storage
+
+1. `Storage::ActiveRecordStore.save` converts tags for JSON or text storage.
+2. Optional fields are written only when their columns exist.
+3. The call row and period rollup updates happen in one transaction.
+4. `ActiveRecordRollups.increment!` updates daily and monthly totals atomically.
+5. Budget reads use period totals when available.
+
+## Dashboard Reads
+
+1. Controllers build a filtered `LlmApiCall` scope.
+2. Dashboard services run targeted aggregate queries.
+3. Helpers render filters, charts, pagination, CSV links, and numeric formatting.
+4. Views render plain ERB with the engine CSS asset.
+
+Dashboard reads do not mutate ledger state. They can be heavier than request-time code, but they still need explicit grouping and indexes.
+
+## Pricing Refresh
+
+1. `llm_cost_tracker:prices:refresh` chooses `ENV["OUTPUT"]`, then `config.prices_file`, then `config/llm_cost_tracker_prices.yml`.
+2. `PriceSync::Fetcher` fetches the maintained LLM Cost Tracker price snapshot.
+3. `PriceSync` validates schema compatibility, gem-version compatibility, and model price shape.
+4. `RegistryWriter` writes a local JSON or YAML registry.
+5. Runtime pricing reloads the local file when its mtime changes.
+
+The gem never fetches pricing from the network during normal request tracking.

data/docs/technical/extension-points.md

@@ -0,0 +1,111 @@
+# Extension Points
+
+Extensions should plug into existing provider-agnostic boundaries. If a new feature needs a provider-specific branch outside ingestion code, revisit the design first.
+
+## Custom Parsers
+
+Use parser registration when a provider or gateway has a response shape the built-ins do not cover.
+
+Expected parser contract:
+
+- `match?(url)` detects supported request URLs.
+- `parse(request_url, request_body, response_status, response_body)` returns `ParsedUsage` or `nil`.
+- `parse_stream(request_url, request_body, response_status, events)` returns `ParsedUsage` or `nil`.
+- `streaming_request?(request_url, request_body)` detects streaming requests when the provider does not use a simple `stream: true` field.
+- `provider_names` returns provider names that can be used by `track_stream(provider: ...)`.
+
+Use `Parsers::Base` helpers for URL matching and stream-event extraction. Use `Parsers::OpenaiUsage` only for OpenAI-shaped usage hashes.
+
+## SDK Integrations
+
+Use SDK integrations when a popular Ruby client does not expose a Faraday middleware stack but returns stable usage objects. RubyLLM and the official `openai` and `anthropic` gems qualify. Faraday-based clients that expose a middleware hook, such as `ruby-openai`'s constructor block, are covered by the Faraday middleware instead. Clients with no stable hook must use the explicit `track` / `track_stream` fallback until an integration exists.
+
+Expected integration contract:
+
+- no hard dependency on the provider SDK
+- fail-fast boot when an explicitly enabled SDK is missing or below the minimum supported version
+- install-time checks for the target classes and methods
+- idempotent `Module#prepend` around narrow resource methods
+- no tracking when the integration is not enabled in configuration
+- canonical usage fields passed to `Tracker.record`
+
+SDK integrations belong under `LlmCostTracker::Integrations`. Do not put SDK object-shape handling in parsers, storage, or pricing.
+
+External integrations can register an adapter with
+`LlmCostTracker::Integrations.register(:name, adapter)`. The adapter must
+respond to `install` and `status`, and enabled names are still selected through
+`config.instrument`.
+
+## OpenAI-Compatible Gateways
+
+Use `config.openai_compatible_providers` when a gateway speaks the OpenAI request and response shape.
+
+This is for shape compatibility, not pricing. Gateway-specific model IDs or discounts belong in `prices_file` or `pricing_overrides`.
+
+## Prices
+
+Use `config.prices_file` for the app's source-controlled price snapshot.
+
+Use `config.pricing_overrides` for urgent or environment-specific overrides that are easier to keep in Ruby.
+
+Supported canonical keys:
+
+- `input`
+- `output`
+- `cache_read_input`
+- `cache_write_input`
+- `batch_input`
+- `batch_output`
+- mode-prefixed keys such as `priority_input` or `batch_cache_read_input`
+
+Provider-specific pricing details must be translated before they reach runtime pricing.
+
+## Tags
+
+Tags are the extension point for application attribution:
+
+- tenant
+- user
+- feature
+- trace
+- job
+- workflow
+- agent session
+
+Use `config.default_tags`, middleware `tags:`, explicit metadata, and `LlmCostTracker.with_tags`. Do not add first-class columns for app dimensions unless the ledger needs that field for provider-agnostic billing behavior.
+
+## Storage
+
+Use `storage_backend = :custom` only when the host app needs to own persistence completely.
+
+Custom storage receives a canonical `Event`. Returning `false` tells the tracker not to run budget checks for that event.
+
+ActiveRecord storage is the production path for dashboards and cross-process budgets.
+
+Storage adapters can register with
+`LlmCostTracker::Storage.register(:name, backend)`. A backend must respond to
+`save(event)` and may expose `verify` for capture diagnostics.
+
+## Dashboard
+
+Dashboard additions should be read-only services under `app/services/llm_cost_tracker/dashboard`.
+
+Keep controller actions thin:
+
+- parse params
+- build filtered scope
+- call services
+- render views
+
+Keep view logic in helpers when it is reused across pages. Do not add JavaScript for dashboard behavior.
+
+## Generators
+
+Generators are installation contracts. New generator behavior should be:
+
+- additive when possible
+- idempotent where Rails generator APIs allow it
+- explicit about destructive or table-rewriting operations
+- covered by generator template specs
+
+Fresh install templates and upgrade generators should stay aligned. If a fresh install gains a column or index, the upgrade path needs a generator unless the next release intentionally makes a breaking install path.

data/docs/technical/module-map.md

@@ -0,0 +1,197 @@
+# Module Map
+
+LLM Cost Tracker is organized around a small set of durable responsibilities. File layout does not need to mirror these modules perfectly, but new code should fit one of these boundaries.
+
+## Public API and Configuration
+
+Primary files:
+
+- `lib/llm_cost_tracker.rb`
+- `lib/llm_cost_tracker/configuration.rb`
+- `lib/llm_cost_tracker/tag_context.rb`
+- `lib/llm_cost_tracker/doctor.rb`
+- `lib/llm_cost_tracker/logging.rb`
+- `lib/llm_cost_tracker/errors.rb`
+
+Responsibilities:
+
+- Expose `configure`, `track`, `track_stream`, `with_tags`, and `enforce_budget!`.
+- Keep configuration immutable after `configure` returns.
+- Merge scoped tags and default tags without leaking state across threads.
+- Report installation and pricing health through `llm_cost_tracker:doctor`.
+
+This module should stay small. It can orchestrate other modules, but it should not contain provider parsing, SQL details, dashboard aggregation, or pricing-source logic.
+
+## SDK Integrations
+
+Primary files:
+
+- `lib/llm_cost_tracker/integrations/*`
+
+Responsibilities:
+
+- Add optional instrumentation for Ruby SDKs without adding provider SDK dependencies.
+- Install narrow, idempotent `Module#prepend` wrappers around stable SDK resource methods.
+- Extract SDK response objects into canonical usage fields.
+- Keep SDK-specific object handling out of `Tracker` and storage.
+
+Integrations are for Ruby SDK object shapes. Parsers are for HTTP and stream payload shapes.
+
+## Ingestion
+
+Primary files:
+
+- `lib/llm_cost_tracker/middleware/faraday.rb`
+- `lib/llm_cost_tracker/stream_collector.rb`
+- `lib/llm_cost_tracker/parsed_usage.rb`
+- `lib/llm_cost_tracker/request_url.rb`
+- `lib/llm_cost_tracker/parsers/*`
+
+Responsibilities:
+
+- Detect supported LLM HTTP requests.
+- Parse provider responses and stream events into `ParsedUsage`.
+- Translate provider-specific fields into canonical usage fields.
+- Preserve app streaming behavior while teeing events for tracking.
+
+Provider-specific code belongs here. The output boundary is `ParsedUsage`, not raw provider JSON.
+
+## Canonical Ledger
+
+Primary files:
+
+- `lib/llm_cost_tracker/tracker.rb`
+- `lib/llm_cost_tracker/event.rb`
+- `lib/llm_cost_tracker/event_metadata.rb`
+- `lib/llm_cost_tracker/usage_breakdown.rb`
+- `lib/llm_cost_tracker/cost.rb`
+- `lib/llm_cost_tracker/unknown_pricing.rb`
+
+Responsibilities:
+
+- Normalize provider, model, usage, tags, latency, streaming flags, and response IDs.
+- Price canonical usage through `Pricing`.
+- Emit `ActiveSupport::Notifications`.
+- Persist the event through the configured storage backend.
+- Run budget checks after successful storage.
+
+This module must remain provider-agnostic. It should never branch on a specific provider model family.
+
+## Pricing
+
+Primary files:
+
+- `lib/llm_cost_tracker/pricing.rb`
+- `lib/llm_cost_tracker/price_registry.rb`
+- `lib/llm_cost_tracker/price_freshness.rb`
+- `lib/llm_cost_tracker/prices.json`
+- `lib/llm_cost_tracker/price_sync/*`
+- `lib/tasks/llm_cost_tracker.rake`
+
+Responsibilities:
+
+- Load bundled prices, local price snapshots, and Ruby overrides.
+- Apply pricing precedence: `pricing_overrides`, `prices_file`, bundled prices.
+- Calculate costs from canonical usage fields.
+- Update local snapshots from the maintained LLM Cost Tracker price registry.
+- Validate snapshot schema compatibility, gem-version compatibility, and price entry shape.
+
+Pricing refresh must not perform boot-time or request-time network work. Runtime pricing uses bundled prices, local files, and in-memory caches.
+
+## Storage
+
+Primary files:
+
+- `lib/llm_cost_tracker/llm_api_call.rb`
+- `lib/llm_cost_tracker/period_total.rb`
+- `lib/llm_cost_tracker/llm_api_call_metrics.rb`
+- `lib/llm_cost_tracker/storage/active_record_store.rb`
+- `lib/llm_cost_tracker/storage/active_record_rollups.rb`
+- `lib/llm_cost_tracker/storage/registry.rb`
+- `lib/llm_cost_tracker/tags_column.rb`
+- `lib/llm_cost_tracker/tag_key.rb`
+- `lib/llm_cost_tracker/tag_sql.rb`
+- `lib/llm_cost_tracker/tag_query.rb`
+- `lib/llm_cost_tracker/tag_accessors.rb`
+- `lib/llm_cost_tracker/period_grouping.rb`
+
+Responsibilities:
+
+- Persist canonical events into ActiveRecord.
+- Hide database-specific tag storage differences.
+- Maintain period rollups for hot-path budget reads.
+- Provide safe scopes for filters, periods, tags, unknown pricing, and reports.
+
+Storage can know about database adapters and optional columns. It should not parse provider responses or fetch price data.
+
+## Budgets and Retention
+
+Primary files:
+
+- `lib/llm_cost_tracker/budget.rb`
+- `lib/llm_cost_tracker/retention.rb`
+- `lib/llm_cost_tracker/storage/active_record_rollups.rb`
+
+Responsibilities:
+
+- Enforce monthly, daily, and per-call guardrails.
+- Support preflight blocking where ActiveRecord rollups are available.
+- Prune old ledger rows in batches.
+- Keep budget checks bounded by maintained aggregates, not by full ledger scans.
+
+Budget behavior is part of the hot path. Any change here must be measured against per-request overhead.
+
+## Dashboard and Reporting
+
+Primary files:
+
+- `lib/llm_cost_tracker/report*.rb`
+- `app/controllers/llm_cost_tracker/*`
+- `app/services/llm_cost_tracker/dashboard/*`
+- `app/helpers/llm_cost_tracker/*`
+- `app/views/llm_cost_tracker/*`
+- `app/assets/llm_cost_tracker/application.css`
+
+Responsibilities:
+
+- Render server-side dashboard pages.
+- Aggregate spend, calls, providers, models, tags, latency, and data quality.
+- Export filtered calls as CSV.
+- Keep dashboard queries explicit and indexed.
+
+Dashboard code may run grouped SQL because it is user-initiated reporting. It must stay server-rendered and must not introduce a JavaScript bundle.
+
+## Rails Integration and Generators
+
+Primary files:
+
+- `lib/llm_cost_tracker/railtie.rb`
+- `lib/llm_cost_tracker/engine.rb`
+- `lib/llm_cost_tracker/assets.rb`
+- `lib/llm_cost_tracker/generators/llm_cost_tracker/*`
+- `config/routes.rb`
+
+Responsibilities:
+
+- Register rake tasks and Faraday middleware.
+- Mount the isolated Rails engine.
+- Generate migrations, initializer, dashboard route, and local price snapshots.
+- Serve dashboard CSS as a fingerprinted engine asset.
+
+Generator templates are public installation contracts. Treat them like API.
+
+## Test Suites
+
+Primary files:
+
+- `spec/llm_cost_tracker/*`
+- `spec/llm_cost_tracker/engine/*`
+- `spec/llm_cost_tracker/dashboard/*`
+- `spec/fixtures/pricing/*`
+- `spec/support/*`
+
+Responsibilities:
+
+- Cover canonical behavior, parser boundaries, pricing precedence, storage rollups, dashboard rendering, generators, and concurrency.
+- Keep request specs plain and stable.
+- Run through `bin/check` before release work or commits that touch code.

data/docs/technical/operational-notes.md

@@ -0,0 +1,77 @@
+# Operational Notes
+
+This file describes runtime constraints that should shape implementation decisions.
+
+## Hot Paths
+
+Hot-path code includes:
+
+- Faraday middleware request and response handling
+- stream collection
+- `Tracker.record`
+- `Pricing.cost_for`
+- ActiveRecord event persistence
+- budget checks
+
+Hot-path code must avoid:
+
+- network calls
+- per-event schema discovery beyond memoized checks
+- full ledger aggregation
+- unbounded stream buffers
+- N+1 queries
+- price-refresh work
+
+## Pricing Freshness
+
+Runtime pricing is local:
+
+1. Ruby overrides
+2. configured local price snapshot
+3. bundled prices
+
+Price update tasks are operational tooling. They can fetch the maintained LLM Cost Tracker price snapshot because the operator runs them intentionally. Request tracking must never depend on live provider pricing pages.
+
+## Budget Reads
+
+Monthly and daily budgets should read `llm_cost_tracker_period_totals` when the table exists. Falling back to summing `llm_api_calls` is an upgrade compatibility path, not the preferred production path.
+
+Per-call budgets are checked from the current event only.
+
+## Retention
+
+Retention may delete old `llm_api_calls`. Period rollups are the durable budget aggregate. Any migration or refactor that changes rollups must preserve the meaning of retained totals or clearly document a breaking change.
+
+## Optional Columns
+
+The gem supports upgrade paths where older apps may not have every column yet. Optional column checks must be memoized and refreshed when ActiveRecord column information is reset.
+
+Do not put table or column checks directly in loops that run for every event without caching.
+
+## Dashboard Queries
+
+Dashboard queries can aggregate because they are user-initiated. They should still use:
+
+- filtered scopes
+- bounded pagination
+- database-side grouping
+- indexes that match common filters
+- single aggregate queries for related counters
+
+Avoid loading ledger rows into Ruby just to count, sum, group, or sort.
+
+## Streaming
+
+Streaming capture must keep the host app's stream behavior intact.
+
+The middleware should collect enough data to parse final usage while bounding memory. When usage never arrives or capture overflows, record an unknown-usage event so Data Quality can surface the gap.
+
+## Release Checks
+
+Run `bin/check` before committing code changes intended for release. It includes full RuboCop, full RSpec, project coverage, and patch coverage for the current diff.
+
+Project coverage defaults to the Codecov target. Patch coverage defaults to 95% so local checks stay stricter than Codecov parser differences. Thresholds can be adjusted locally with `PROJECT_COVERAGE_MIN`, `PATCH_COVERAGE_MIN`, or `COVERAGE_BASE`.
+
+For the closest match to the Codecov upload job, run `BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bin/check`.
+
+Docs-only changes do not require the full suite, but any code, generator, migration, parser, pricing, dashboard, or storage change does.

data/docs/upgrading.md

@@ -0,0 +1,46 @@
+# Upgrading
+
+LLM Cost Tracker is still moving quickly, so upgrades should be explicit:
+inspect the changelog, run doctor, and apply only the generators your schema is
+missing.
+
+The version-by-version upgrade guide is moving here from the README.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Changelog](../CHANGELOG.md)
+- [Quickstart](../README.md#quickstart)
+- [Operations](operations.md)
+
+## Schema Generators
+
+Existing installs can add newer optional columns through focused generators:
+
+```bash
+bin/rails generate llm_cost_tracker:add_period_totals
+bin/rails generate llm_cost_tracker:add_streaming
+bin/rails generate llm_cost_tracker:add_provider_response_id
+bin/rails generate llm_cost_tracker:add_usage_breakdown
+bin/rails generate llm_cost_tracker:upgrade_tags_to_jsonb
+bin/rails generate llm_cost_tracker:upgrade_cost_precision
+bin/rails generate llm_cost_tracker:add_latency_ms
+bin/rails db:migrate
+bin/rails llm_cost_tracker:doctor
+```
+
+On PostgreSQL, `upgrade_tags_to_jsonb` rewrites `llm_api_calls`. For large
+tables, run it during a maintenance window or replace it with a two-phase
+backfill.
+
+## Upgrade Habit
+
+Run:
+
+```bash
+bin/rails llm_cost_tracker:doctor
+```
+
+Doctor tells you which optional columns and production-hardening pieces are still
+missing.

data/lib/llm_cost_tracker/capture_verifier.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "storage/dispatcher"
+
+module LlmCostTracker
+  class CaptureVerifier
+    Check = Data.define(:status, :name, :message)
+
+    class << self
+      def call = new.checks
+
+      def report(checks = call)
+        (["LLM Cost Tracker capture verification"] + checks.map { |check| format_check(check) }).join("\n")
+      end
+
+      def healthy?(checks = call)
+        checks.none? { |check| check.status == :error }
+      end
+
+      private
+
+      def format_check(check)
+        "[#{check.status}] #{check.name}: #{check.message}"
+      end
+    end
+
+    def checks
+      [
+        enabled_check,
+        *integration_checks,
+        *storage_checks
+      ].compact
+    end
+
+    private
+
+    def enabled_check
+      return Check.new(:ok, "tracking", "enabled") if LlmCostTracker.configuration.enabled
+
+      Check.new(:error, "tracking", "disabled; set config.enabled = true before verifying capture")
+    end
+
+    def integration_checks
+      enabled = LlmCostTracker.configuration.instrumented_integrations
+      if enabled.empty?
+        return [
+          Check.new(:ok, "sdk integrations", "none enabled; Faraday middleware and manual capture remain available")
+        ]
+      end
+
+      LlmCostTracker::Integrations.checks.map do |check|
+        Check.new(check.status, "sdk integration #{check.name}", check.message)
+      end
+    end
+
+    def storage_checks
+      backend = LlmCostTracker::Storage::Registry.fetch(LlmCostTracker.configuration.storage_backend)
+      unless backend.respond_to?(:verify)
+        return [
+          Check.new(:warn, "storage", "#{LlmCostTracker.configuration.storage_backend} backend has no verifier")
+        ]
+      end
+
+      backend.verify.map do |check|
+        Check.new(check.status, check.name, check.message)
+      end
+    rescue LlmCostTracker::Error => e
+      [Check.new(:error, "storage", e.message)]
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration/instrumentation.rb

@@ -31,7 +31,7 @@ module LlmCostTracker
     end
 
     def available_instrumentation_names
-      Integrations::Registry::INTEGRATIONS.keys
+      Integrations::Registry.names
     end
   end
 end

data/lib/llm_cost_tracker/configuration/storage_backend.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module ConfigurationStorageBackend
+    def storage_backend=(value)
+      ensure_shared_configuration_mutable!
+      @storage_backend = normalize_storage_backend(value)
+    end
+
+    private
+
+    def normalize_storage_backend(value)
+      value = :log if value.nil?
+      value = value.to_sym
+      return value if self.class::STORAGE_BACKENDS.include?(value)
+      return value if defined?(Storage::Registry) && Storage::Registry.registered?(value)
+
+      names = if defined?(Storage::Registry)
+                Storage::Registry.names
+              else
+                self.class::STORAGE_BACKENDS
+              end
+      raise Error, "Unknown storage_backend: #{value.inspect}. Use one of: #{names.join(', ')}"
+    end
+  end
+end