ask-llm-providers 0.1.2 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0b23746b8ee8cc98e50c44f9e88df977ea81d9214bbda9a25be770021234cc2
-  data.tar.gz: 2a2e628b12eb8e731ea9d46ae0f4076dd42591f03db0cf50759d77d6485e748e
+  metadata.gz: fcbf569b97e70a5c06deac427eb7cc500bb959295b2f8ce10ed20d9698cec241
+  data.tar.gz: 20a6ac87a6a4e35d84d3596d604644e2280616676399632ce2b481c3591a96f2
 SHA512:
-  metadata.gz: 4e31b5f82ae3aaab7a7bf337df1ebd5afc20b272efc2b630523145bbf82ebbd12faddcaacdb30e531df3cd3a379a82d9d2e96b97d9ff33877eff6eb0c638d320
-  data.tar.gz: 2db527541cb1a8934c6f5ff2e62fbb8ebddf633600e332b040231461eaf9c9b5cb37ec3a70f0079a85404cf8b5fb3751c4f9b88ef075366681044d046ebfdd6b
+  metadata.gz: 57f783f4c2bdd7335e45d06f177df09ea565acec8cf65d4cc9bdadb747276b94e944cdacf0505dc29e553697ad21ef7574a357c1d7ac5f5386bc59c76fa4b835
+  data.tar.gz: d4ffb871a8e1702aaa1b27763bb1481689f1c61f8c55efd27de0db198cf3f9482ca691c5c0e36c0806cf11057178418a3cfd467016afd79207d40dbe39214328

data/CHANGELOG.md

@@ -0,0 +1,181 @@
+## [0.8.1] — 2026-07-17
+
+### Added
+
+- **Rich error categories in HTTP mapper** — `Ask::LLM::HTTP.map_error` now sets `category`, `rate_limit_type`, and `retry_after` on `RateLimitError` instances. Rate limit type is detected from error message keywords (token, budget, concurrent, requests). `retry_after` is extracted from response headers.
+
+## [0.8.0] — 2026-07-17
+
+### Added
+
+- **OpenRouter model source** (`Ask::LLM::Sources::OpenRouter`) — fetches model data from OpenRouter API and fills gaps that models.dev doesn't cover. Adds models for providers like Groq, Together, Fireworks, Cerebras, Meta, Moonshot, Nvidia NIM that aren't in models.dev. Merges with existing models.dev data — models.dev takes priority for overlapping models.
+- **`CostCalculator.per_million`** — returns per-million token rates for quick display: `{ input: 2.5, output: 10.0, cache_read: 1.25 }`.
+- **Audio token costing** — `calculate` and `breakdown` now accept `audio_input_tokens` and `audio_output_tokens` parameters. Costs are computed from `audio_tokens` pricing data.
+- **Tiered pricing** — both `calculate` and `breakdown` accept a `tier:` parameter (`:standard` or `:batch`) that selects the appropriate rate tier.
+- **`rake models:update`** — now fetches both models.dev and OpenRouter in sequence.
+
+### Changed
+
+- **Model coverage: 62 → 406 models** across 12 providers, with 397 (98%) having full pricing data.
+- **OpenRouter source added** — providers without models.dev coverage (meta, moonshot, nvidia_nim) now have bundled models.
+- **`build_model_info`** — pricing hashes are deep-symbolized. `Date.parse` failures handled gracefully via `safe_parse_date`.
+
+## [0.7.0] — 2026-07-17
+
+### Added
+
+- **`Ask::LLM::Sources::ModelsDev`** — fetches model data from `models.dev` API and writes enriched per-provider JSON files with pricing, capabilities, and modalities. Run `rake models:update` before each release to keep bundled model data current.
+- **`Ask::LLM::CostCalculator`** — calculates LLM API costs from model pricing data. Supports input, output, cache read/write, and reasoning tokens.
+
+### Changed
+
+- **Model coverage expanded** — from 62 to 289 models across 10 providers, with 284 (98%) having full pricing data. Generated from models.dev API instead of hand-written.
+- **`build_model_info` now deep-symbolizes pricing keys** — pricing hashes loaded from JSON now use symbol keys (`:text_tokens`, `:standard`, `:input_per_million`) matching the format produced by `ModelsDevParser` in ask-core.
+- **`build_model_info` handles date parsing safely** — `Date.parse` failures no longer silently destroy the entire model entry via a broad `rescue Date::Error`. Invalid dates are gracefully set to `nil` via `safe_parse_date`.
+
+### Fixed
+
+- **Pricing data loss bug** — `rescue Date::Error` in `build_model_info` was catching exceptions from the entire method body, including date parsing and pricing construction. When any model had an unparseable date, its ModelInfo was created with only `id` and `provider`, silently discarding pricing, capabilities, modalities, and all other fields.
+- **Pricing key inconsistency** — pricing loaded from JSON had string keys while pricing from `ModelsDevParser` (ask-core) had symbol keys. Both formats now consistently use symbol keys.
+
+## [0.6.1] — 2026-07-17
+
+### Added
+
+- **`Ask::LLM::CostCalculator`** — calculate LLM API costs from model pricing data. Supports input, output, cache read/write, and reasoning tokens. Returns cost in USD or nil if no pricing data available. Works with any object responding to `#pricing` (Ask::ModelInfo, raw hash, etc.).
+- **`CostCalculator.breakdown`** — returns a component-by-component cost breakdown hash.
+
+## [0.6.0] — 2026-07-17
+
+### Added
+
+- **14 new OpenAI-compatible providers** — aiml, ai21, anyscale, deepinfra, featherless, friendli, github, hyperbolic, meta, nebius, novita, nscale, nvidia_nim, sambanova. Each is one line in the registry. Total OpenAI-compatible providers: 26. Total providers: 33.
+- **Auto-generated tests** — `OpenAICompatibleTest` now builds its test list from `OPENAI_COMPATIBLE` dynamically. Adding a provider automatically generates 5 identity tests (registered, slug, capabilities, api_base, requires_api_key).
+
+## [0.5.0] — 2026-07-17
+
+### Added
+
+- **OpenAI-compatible provider registry** (`Ask::LLM::OPENAI_COMPATIBLE`) — 12 providers defined as data, not classes. Adding a new OpenAI-compatible API (Groq, Together, Fireworks, etc.) is one line in the registry. No new file, no subclass.
+- **`Ask::Providers::OpenAICompatible` class** — single class handling all registered providers by reading from the registry. Each provider gets an anonymous subclass with its slug, api_base, env var mapping, and quirks (reasoning_content, extra_headers) set from config.
+- **Unified test** — `OpenAICompatibleTest` dynamically tests every registered provider: identity, slug, capabilities, api_base, env var resolution, request building, response parsing, streaming, and tool formatting.
+
+### Removed
+
+- **5 subclass files** — `deepseek.rb`, `openrouter.rb`, `opencode.rb`, `opencode_go.rb`, `mimo.rb` deleted. Replaced by registry entries.
+- **DeepSeek-specific test file** — covered by the unified test.
+
+## [0.4.0] — 2026-07-16
+
+### Added
+
+- **`Ask::LLM::ProviderConfig` transformation contract** — Shared module that every provider includes, defining the wire-format interface: `build_request`, `parse_response`, `parse_stream`, `format_tools`, `format_message`. Adding a new provider is now mechanical — implement five methods and the provider works. (Inspired by LiteLLM's `BaseConfig` pattern.)
+- **`BaseProviderTests` shared test module** — Every provider test includes this module, which enforces 22 contract tests (interface methods, slug, capabilities, config, request building, error mapping) inherited from LiteLLM's `BaseLLMChatTest` approach. Adding a new provider gives you 22 tests for free.
+- **Comprehensive per-provider tests** — Each provider now has dedicated tests for `build_request`, `parse_response`, `parse_stream`, `format_message`, `format_tools`, `parse_error`, and streaming — covering happy paths, edge cases, and error conditions. Total test count: 341 (up from ~33 in v0.1.0).
+
+### Changed
+
+- **Provider refactoring** — OpenAI, Anthropic, Google, Bedrock, Ollama, Cloudflare, and Mistral providers now include `Ask::LLM::ProviderConfig` and implement its transformation contract. The `chat` method in each is a clean orchestrator: build request → HTTP → parse response. Internal methods (`build_chat_payload`, `process_chunk`, etc.) are renamed to the contract standard.
+- **Subclass compatibility** — DeepSeek, OpenRouter, OpenCode, OpenCodeGo, and Mimo (all OpenAI subclasses) inherit the transformation contract unchanged. Their `format_messages` overrides continue to work through `build_request`.
+
+### Removed
+
+- **Dead files** — Removed `lib/ask/provider/config.rb` (moved to `lib/ask/llm/provider_config.rb` to avoid namespace collision with `Ask::Provider` class).
+
+## [0.3.1] — 2026-07-14
+
+### Removed
+- `Ask::ModelCatalog::PROVIDER_PREFERENCE` removed from ask-core. `find(model_id)` now returns all matching models — no more provider preference disambiguation at the catalog level.
+
+## [0.3.0] — 2026-07-14
+
+### Added
+- **Model catalog system** — `Ask::LLM::Catalog` loads model definitions from per-provider JSON files (`lib/ask/llm/models/*.json`), user overrides (`~/.ask-llm-providers/models.json`), and provider API `list_models()` on explicit refresh.
+- **Per-provider model JSONs** — 12 JSON files (openai, anthropic, gemini, deepseek, opencode, opencode_go, mimo, openrouter, ollama, mistral, bedrock, cloudflare) with id, name, provider, capabilities, context window, modalities, and pricing.
+- **Model aliases** — `Ask::LLM::Aliases` resolves short names (e.g. `claude-sonnet-4` → `claude-sonnet-4-6`). Alias entries are automatically registered into `Ask::ModelCatalog` so `ModelCatalog.find` works with alias names.
+- **User config support** — `~/.ask-llm-providers/models.json` overrides bundled model fields or adds custom models.
+- **`opencode.json` includes `deepseek-v4-flash`** — matches the default model configuration.
+
+### Changed
+- Removed hardcoded `Ask::LLM::Models::OPENAI_MODELS` constants — replaced with catalog-driven model loading.
+- `Ask::LLM::Aliases.resolve` now aliases `deepseek-v4` → `deepseek-v4-flash`, `gpt-4o-latest` → `gpt-4o`, `gpt-4.1-latest` → `gpt-4.1`.
+
+### Fixed
+- Model entries now include `"provider"` field in JSON files (was missing from generated data).
+- User config merges properly override bundled values (was keeping old values on conflict).
+
+## [0.2.2] — 2026-06-25
+
+### Changed
+- Extended per-provider tests (Anthropic 18t, Google 14t, DeepSeek 16t, Mistral, Ollama, Cloudflare, Bedrock). Fixed providers_test.rb syntax error. RuboCop, overcommit, gemspec test, SimpleCov, CI.
+# Changelog
+
+## [0.1.0] — 2026-06-09
+
+Initial release of `ask-llm-providers`, all LLM providers for the ask-rb ecosystem.
+
+### Added
+
+- **OpenAI provider** — Chat Completions API with streaming, tool calls, vision, structured output, embeddings
+- **Anthropic provider** — Messages API with thinking blocks, tool use, prompt caching
+- **Google Gemini provider** — `generateContent` API with function calling, streaming, embeddings
+- **Amazon Bedrock provider** — Converse API with tool configuration
+- **Ollama provider** — Local LLM inference with chat and embeddings endpoints
+- **Mistral AI provider** — OpenAI-compatible API with embeddings support
+- **Cloudflare provider** — Workers AI direct endpoint and AI Gateway passthrough
+- **Error mapping** — Provider-specific HTTP errors → `Ask::Error` types (rate limit, auth, context exceeded, etc.)
+- **Provider registration** — All providers auto-registered with `Ask::Provider` on gem load
+- **Capabilities introspection** — Each provider exposes supported capabilities
+- **Shared HTTP infrastructure** — `Ask::LLM::HTTP` with Faraday connection builder and SSE streaming
+- **Test suite** — 33 tests across all providers and error mapping
+
+## [0.1.8] — 2026-06-18
+
+### Added
+
+- **OpenRouter provider** — `Ask::Providers::OpenRouter`, reads `OPENROUTER_API_KEY`,
+  sets `HTTP-Referer` and `X-Title` headers.
+
+### Fixed
+
+- **`normalize_config` ENV resolution** — Removed broken monkey-patch that defined
+  `normalize_config` on `Object` instead of within the `OpenAI` class. Now resolves
+  `api_key` from: explicit config → subclass-specific key → `ENV` var →
+  `Ask::Auth.resolve` chain. All OpenAI-compatible subclasses (DeepSeek, OpenCode,
+  OpenCodeGo, Mimo, OpenRouter) inherit the fix.
+
+## [0.1.9] — 2026-06-18
+
+### Fixed
+
+- **`format_messages` with Hash tool_calls** — Tool calls can arrive as Hash (keyed
+  by call_id) from some chat implementations, or as Array. The method now detects
+  both formats with `tc.is_a?(Hash) ? tc.values : tc`. Also handles `OpenStruct`
+  tool call objects via `.respond_to?` checks instead of assuming Hash accessors.
+
+## [0.2.0] — 2026-06-19
+
+### Fixed
+
+- **SSE buffering across all streaming providers** — TCP fragmentation in
+  Faraday's `on_data` callback caused silent data loss when SSE events were
+  split across packets. Added persistent `@_sse_buffer` with complete-event
+  extraction via `Ask::LLM::SSEBuffer` module. Affected providers:
+  OpenAI, Anthropic, Cloudflare, Google, Ollama. All OpenAI-compatible
+  subclasses inherit the fix.
+
+### Added
+
+- **`Ask::LLM::SSEBuffer`** — Shared module providing `init_sse_buffer` and
+  `each_sse_event(raw)` for SSE buffering across streaming callbacks.
+- **SSE buffering tests** — 5 new tests covering fragmented data, event
+  boundaries, multiple events, and `[DONE]` sentinel.
+
+## [0.1.10] — 2026-06-18
+
+### Fixed
+
+- **`chat_stream` nil response body** — Streaming requests consume the response body
+  via `on_data` callback, leaving `resp.body` as `nil`. `JSON.parse(nil)` raised
+  `TypeError: no implicit conversion of nil into String`. Now checks
+  `resp.body` before parsing.

data/lib/ask/llm/aliases.json

@@ -0,0 +1,11 @@
+{
+  "claude-sonnet-4": "claude-sonnet-4-6",
+  "claude-sonnet-4-5": "claude-sonnet-4-6",
+  "claude-opus-4": "claude-opus-4-7",
+  "claude-opus-4-5": "claude-opus-4-7",
+  "claude-haiku-4": "claude-haiku-4-5",
+  "gemini-3": "gemini-3-flash",
+  "deepseek-v4": "deepseek-v4-flash",
+  "gpt-4o-latest": "gpt-4o",
+  "gpt-4.1-latest": "gpt-4.1"
+}

data/lib/ask/llm/aliases.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module LLM
+    # Resolves model name aliases to canonical model IDs.
+    #
+    # Aliases are defined in aliases.json and allow users to refer
+    # to models by shorter or more familiar names. Resolution is
+    # provider-scoped — you can alias "claude-sonnet-4" to different
+    # canonical IDs depending on which provider serves it.
+    #
+    #   Ask::LLM::Aliases.resolve("claude-sonnet-4")
+    #   # => "claude-sonnet-4-6"
+    #
+    # Aliases are loaded lazily from the bundled JSON file.
+    module Aliases
+      ALIASES_PATH = File.expand_path("aliases.json", __dir__)
+
+      class << self
+        # Resolve an alias to a canonical model ID.
+        # Returns the input name unchanged if no alias is registered.
+        def resolve(name)
+          load_aliases unless @aliases
+          @aliases[name.to_s] || name.to_s
+        end
+
+        # Register a custom alias at runtime.
+        def register(short_name, canonical_id)
+          load_aliases unless @aliases
+          @aliases[short_name.to_s] = canonical_id.to_s
+        end
+
+        # Reload aliases from the bundled JSON file.
+        def reload!
+          @aliases = nil
+          load_aliases
+        end
+
+        # All registered aliases (for introspection).
+        def all
+          load_aliases unless @aliases
+          @aliases.dup
+        end
+
+        private
+
+        def load_aliases
+          @aliases = {}
+          path = ALIASES_PATH
+          return unless File.exist?(path)
+
+          raw = JSON.parse(File.read(path))
+          raw.each { |k, v| @aliases[k.to_s] = v.to_s }
+        rescue JSON::ParserError
+          # Invalid aliases file — log and use empty map
+        end
+      end
+    end
+  end
+end

data/lib/ask/llm/catalog.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "json"
+require "date"
+require "fileutils"
+
+module Ask
+  module LLM
+    # Orchestrates model catalog loading from multiple sources:
+    #
+    #   1. Bundled JSON files in lib/ask/llm/models/*.json (shipped with the gem)
+    #   2. ~/.ask-llm-providers/models.json (user-defined overrides)
+    #   3. Provider API list_models() calls (on explicit refresh!)
+    #
+    # Loaded models are registered into Ask::ModelCatalog for use
+    # by ask-agent, ask-mcp, and llm-proxy.
+    #
+    #   Ask::LLM::Catalog.load!  # load bundled + user config
+    #   Ask::LLM::Catalog.refresh!  # also fetch from provider APIs
+    #
+    class Catalog
+      class Error < StandardError; end
+      class LoadError < Error; end
+
+      USER_CONFIG_PATH = File.expand_path("~/.ask-llm-providers/models.json").freeze
+
+      class << self
+        # Load bundled model definitions and user overrides into Ask::ModelCatalog.
+        # Idempotent — subsequent calls clear and reload.
+        def load!
+          instance.clear
+          instance.load_bundled
+          instance.load_user_config
+          instance.register_all
+          true
+        end
+
+
+
+        # Like load! but also fetches model lists from configured providers'
+        # list_models() APIs. Unknown models are added with minimal metadata.
+        def refresh!
+          load!
+          instance.fetch_from_providers
+          instance.register_all
+          true
+        end
+
+      private
+
+      def symbolize_keys(hash)
+        hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+      end
+
+        def instance
+          @instance ||= new
+        end
+      end
+
+      def initialize
+        @entries = []
+        @model_keys = Set.new
+      end
+
+      def clear
+        @entries.clear
+        @model_keys.clear
+      end
+
+      # Load bundled model JSONs from the gem's lib/ask/llm/models/ directory.
+      def load_bundled
+        pattern = File.expand_path("models/*.json", __dir__)
+        Dir[pattern].sort.each do |path|
+          raw = JSON.parse(File.read(path))
+          raw.each { |entry| add_entry(entry) }
+        end
+      end
+
+      # Load user-defined model overrides from ~/.ask-llm-providers/models.json.
+      # Silently skipped if the file doesn't exist.
+      def load_user_config
+        path = USER_CONFIG_PATH
+        return unless File.exist?(path)
+
+        raw = JSON.parse(File.read(path))
+        unless raw.is_a?(Array)
+          warn "Warning: #{path} should be a JSON array of model entries, got #{raw.class}"
+          return
+        end
+
+        raw.each { |entry| merge_or_add(entry) }
+      rescue JSON::ParserError => e
+        warn "Warning: Failed to parse #{path}: #{e.message}"
+      end
+
+      # Fetch model lists from all configured providers via their list_models() API.
+      # Adds unknown models with minimal metadata (no capability guessing).
+      def fetch_from_providers
+        Ask::Provider.providers.each do |slug, provider_class|
+          next unless provider_class.configured?(nil)
+
+          begin
+            provider = provider_class.new
+            models = provider.list_models
+            models.each do |m|
+              add_entry(m) unless @model_keys.include?([m[:id], slug.to_s])
+            end
+          rescue StandardError => e
+            warn "Warning: Failed to fetch models from #{slug}: #{e.message}"
+          end
+        end
+      end
+
+      # Register all accumulated entries into Ask::ModelCatalog.
+      # Also registers alias entries so models can be found by alias name.
+      def register_all
+        catalog = Ask::ModelCatalog.instance
+        catalog.instance_variable_set(:@models, [])
+
+        @entries.each do |entry|
+          info = build_model_info(entry)
+          catalog.register(info)
+        end
+
+        register_alias_entries
+      end
+
+      private
+
+      # For each alias (short_name → canonical_id), register a duplicate
+      # ModelInfo for every canonical entry whose id matches.
+      def register_alias_entries
+        Ask::LLM::Aliases.all.each do |short_name, canonical_id|
+          next if short_name == canonical_id
+
+          @entries.each do |entry|
+            next unless entry["id"] == canonical_id || entry[:id] == canonical_id
+
+            alias_entry = entry.merge("id" => short_name)
+            info = build_model_info(alias_entry)
+            Ask::ModelCatalog.instance.register(info)
+          end
+        end
+      end
+
+      def symbolize_keys(hash)
+        hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+      end
+
+      def deep_symbolize_keys(hash)
+        hash.each_with_object({}) { |(k, v), h|
+          hk = k.respond_to?(:to_sym) ? k.to_sym : k
+          h[hk] = v.is_a?(Hash) ? deep_symbolize_keys(v) : v
+        }
+      end
+
+      def add_entry(entry)
+        key = entry_key(entry)
+        return if @model_keys.include?(key)
+
+        @entries << entry
+        @model_keys << key
+      end
+
+      def merge_or_add(entry)
+        key = entry_key(entry)
+        existing = @entries.find { |e| entry_key(e) == key }
+
+        if existing
+          existing.merge!(entry)
+        else
+          @entries << entry
+          @model_keys << key
+        end
+      end
+
+      def entry_key(entry)
+        id = entry["id"] || entry[:id]
+        provider = entry["provider"] || entry[:provider]
+        [id, provider.to_s]
+      end
+
+      def build_model_info(entry)
+        e = entry.transform_keys(&:to_sym)
+
+        modalities = symbolize_keys(e[:modalities]) if e[:modalities]
+
+        pricing = {}
+        if e[:pricing] && e[:pricing].any?
+          deep_symbolize_keys(e[:pricing]).each { |k, v| pricing[k] = v }
+        end
+
+        knowledge_cutoff = safe_parse_date(e[:knowledge_cutoff])
+        created_at = safe_parse_date(e[:created_at])
+
+        Ask::ModelInfo.new(
+          id: e[:id],
+          name: e[:name] || e[:id],
+          provider: e[:provider],
+          family: e[:family],
+          capabilities: Array(e[:capabilities]),
+          context_window: e[:context_window],
+          max_output_tokens: e[:max_output_tokens],
+          modalities: modalities || { input: %w[text], output: %w[text] },
+          pricing: pricing,
+          knowledge_cutoff: knowledge_cutoff,
+          created_at: created_at,
+          metadata: (e[:metadata] || {}).merge(source: e[:metadata]&.dig("source") || "bundled")
+        )
+      end
+
+      def safe_parse_date(value)
+        return nil if value.nil?
+        return value if value.is_a?(Date)
+        Date.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/ask/llm/cost_calculator.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Ask
+  module LLM
+    # Calculate LLM API costs from model pricing data.
+    module CostCalculator
+      MILLION = 1_000_000
+
+      class << self
+        # Calculate total cost in USD for a model invocation.
+        #
+        # @param model [Ask::ModelInfo, #pricing] the model or a pricing hash
+        # @param input_tokens [Integer]
+        # @param output_tokens [Integer]
+        # @param cache_read_tokens [Integer]
+        # @param cache_write_tokens [Integer]
+        # @param reasoning_tokens [Integer]
+        # @param audio_input_tokens [Integer]
+        # @param audio_output_tokens [Integer]
+        # @param tier [Symbol] pricing tier (:standard or :batch)
+        # @return [Float, nil] cost in USD, or nil if no pricing data
+        def calculate(model, input_tokens: 0, output_tokens: 0,
+                      cache_read_tokens: 0, cache_write_tokens: 0,
+                      reasoning_tokens: 0,
+                      audio_input_tokens: 0, audio_output_tokens: 0,
+                      tier: :standard)
+          pricing = extract_pricing(model)
+          return nil unless pricing
+
+          rates = pricing.dig(:text_tokens, tier) or return nil
+
+          sum = cost(input_tokens, rates[:input_per_million])
+          sum += cost(output_tokens, rates[:output_per_million])
+          sum += cost(cache_read_tokens, rates[:cache_read_input_per_million])
+          sum += cost(cache_write_tokens, rates[:cache_write_input_per_million])
+
+          if reasoning_tokens > 0
+            rate = rates[:reasoning_output_per_million] || rates[:output_per_million]
+            sum += cost(reasoning_tokens, rate)
+          end
+
+          if audio_input_tokens > 0 || audio_output_tokens > 0
+            audio = pricing.dig(:audio_tokens, tier)
+            sum += cost(audio_input_tokens, audio[:input_per_million]) if audio
+            sum += cost(audio_output_tokens, audio[:output_per_million]) if audio
+          end
+
+          sum
+        end
+
+        # Per-million rates for quick display.
+        #
+        # @param model [Ask::ModelInfo, #pricing]
+        # @param tier [Symbol] (:standard or :batch)
+        # @return [Hash, nil]
+        def per_million(model, tier: :standard)
+          pricing = extract_pricing(model)
+          return nil unless pricing
+
+          rates = pricing.dig(:text_tokens, tier) or return nil
+
+          {
+            input: rates[:input_per_million],
+            output: rates[:output_per_million],
+            cache_read: rates[:cache_read_input_per_million],
+            cache_write: rates[:cache_write_input_per_million],
+            reasoning: rates[:reasoning_output_per_million]
+          }.compact
+        end
+
+        # Per-component cost breakdown.
+        #
+        # @return [Hash, nil]
+        def breakdown(model, input_tokens: 0, output_tokens: 0,
+                      cache_read_tokens: 0, cache_write_tokens: 0,
+                      reasoning_tokens: 0,
+                      audio_input_tokens: 0, audio_output_tokens: 0,
+                      tier: :standard)
+          pricing = extract_pricing(model)
+          return nil unless pricing
+
+          rates = pricing.dig(:text_tokens, tier) or return nil
+
+          result = {
+            input: cost(input_tokens, rates[:input_per_million]),
+            output: cost(output_tokens, rates[:output_per_million]),
+            cache_read: cost(cache_read_tokens, rates[:cache_read_input_per_million]),
+            cache_write: cost(cache_write_tokens, rates[:cache_write_input_per_million]),
+            reasoning: cost(reasoning_tokens, rates[:reasoning_output_per_million] || rates[:output_per_million])
+          }.compact
+
+          if audio_input_tokens > 0 || audio_output_tokens > 0
+            audio = pricing.dig(:audio_tokens, tier)
+            result[:audio_input] = cost(audio_input_tokens, audio[:input_per_million]) if audio
+            result[:audio_output] = cost(audio_output_tokens, audio[:output_per_million]) if audio
+          end
+
+          result
+        end
+
+        private
+
+        def extract_pricing(model)
+          model.respond_to?(:pricing) ? model.pricing : model
+        end
+
+        def cost(tokens, rate)
+          return 0.0 unless rate && tokens > 0
+          (tokens * rate) / MILLION.to_f
+        end
+      end
+    end
+  end
+end