ruby_llm-agents 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82355e2a179ddaf2f5003b2cbd972f373b2ca49cdcc2847535aec89fb18ed046
-  data.tar.gz: '09656de02af43adafdfe2615d1bfcb67aee76602fd0699d0f739eda731f29d8d'
+  metadata.gz: 4cb913b70bd04950b91cc665ef9e2af84aa009618dffb7072e9d6b8ae389bc77
+  data.tar.gz: 479066023ed864ee78c317c37f64e92c8fb2b503215ac0280e097a14d9ba2ba7
 SHA512:
-  metadata.gz: a5c8b20da41f0f73b8fdbffb809cecc726f1e7e6030d8351c5b994c58192b8d18da7693fa8fadec603f8dfb29ab7dd40907877600f58af185ab9d5542a884dcf
-  data.tar.gz: b6c0c90038a87f2824ff52b0bedd901528e291748a18caff4fd2df403affd351bf7cdf05db3042e6daae05d602c672f90a9a97434e6f54f9834c337ebae1a607
+  metadata.gz: 6e521f3b9f022228e178618ff4e9eebb7de1486e96a2aec9c09215b76c16306210c6a7fd7ce0309b36e442886e4b7feb65788586b904d33e22f5b235c3d9bea2
+  data.tar.gz: 8a7bb1235fa527283a4296d56bd95dda94b87f2c1419f75f6efc46f6aa1e1b74957d1cd0761b9763f61f9e9bfefae15c5028b0cb8a89295b1450df3c7865580b

data/README.md

@@ -100,6 +100,50 @@ result = Embedders::DocumentEmbedder.call(texts: ["Hello", "World", "Ruby"])
 result.vectors      # => [[...], [...], [...]]
 ```
 
+```ruby
+# Message classification and routing
+class SupportRouter < ApplicationAgent
+  include RubyLLM::Agents::Routing
+
+  model "gpt-4o-mini"
+  temperature 0.0
+  cache_for 1.hour
+
+  route :billing,   "Billing, charges, refunds, payments"
+  route :technical,  "Bugs, errors, crashes, technical issues"
+  route :sales,      "Pricing, plans, upgrades, discounts"
+  default_route :general
+end
+
+result = SupportRouter.call(message: "I was charged twice")
+result.route          # => :billing
+result.total_cost     # => 0.00008
+```
+
+```ruby
+# Text-to-speech and speech-to-text
+# app/agents/audio/podcast_speaker.rb
+module Audio
+  class PodcastSpeaker < ApplicationSpeaker
+    model "tts-1"
+    voice "onyx"
+    speed 0.95
+    output_format :aac
+    streaming true
+  end
+end
+
+result = Audio::PodcastSpeaker.call(text: "Welcome to the show!")
+result.audio        # => Binary audio data
+result.duration     # => 1.5
+result.save_to("episode.aac")
+
+# Speech-to-text transcription
+result = Audio::MeetingTranscriber.call(audio: "standup.mp3")
+result.text         # => "Good morning everyone..."
+result.word_count   # => 5432
+```
+
 ```ruby
 # Image generation, analysis, and pipelines
 # app/agents/images/logo_generator.rb
@@ -127,6 +171,7 @@ result.save("logo.png")
 | **Cost Analytics** | Track spending by agent, model, tenant, and time period | [Analytics](https://github.com/adham90/ruby_llm-agents/wiki/Execution-Tracking) |
 | **Reliability** | Automatic retries, model fallbacks, circuit breakers with block DSL | [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) |
 | **Budget Controls** | Daily/monthly limits with hard and soft enforcement | [Budgets](https://github.com/adham90/ruby_llm-agents/wiki/Budget-Controls) |
+| **Multi-Source Pricing** | 7-source pricing cascade with caching for all model types | [Pricing](https://github.com/adham90/ruby_llm-agents/wiki/Pricing) |
 | **Multi-Tenancy** | Per-tenant API keys, budgets, circuit breakers, and execution isolation | [Multi-Tenancy](https://github.com/adham90/ruby_llm-agents/wiki/Multi-Tenancy) |
 | **Async/Fiber** | Concurrent execution with Ruby fibers for high-throughput workloads | [Async](https://github.com/adham90/ruby_llm-agents/wiki/Async-Fiber) |
 | **Dashboard** | Real-time Turbo-powered monitoring UI | [Dashboard](https://github.com/adham90/ruby_llm-agents/wiki/Dashboard) |
@@ -135,6 +180,7 @@ result.save("logo.png")
 | **Attachments** | Images, PDFs, and multimodal support | [Attachments](https://github.com/adham90/ruby_llm-agents/wiki/Attachments) |
 | **Embeddings** | Vector embeddings with batching, caching, and preprocessing | [Embeddings](https://github.com/adham90/ruby_llm-agents/wiki/Embeddings) |
 | **Image Operations** | Generation, analysis, editing, pipelines with cost tracking | [Images](https://github.com/adham90/ruby_llm-agents/wiki/Image-Generation) |
+| **Routing** | Message classification and routing with auto-generated prompts, inline classify | [Routing](https://github.com/adham90/ruby_llm-agents/wiki/Routing) |
 | **Audio** | Text-to-speech (OpenAI, ElevenLabs), speech-to-text, dynamic pricing, 28+ output formats, dashboard audio playback | [Audio](https://github.com/adham90/ruby_llm-agents/wiki/Audio) |
 | **Alerts** | Slack, webhook, and custom notifications | [Alerts](https://github.com/adham90/ruby_llm-agents/wiki/Alerts) |
 
@@ -213,10 +259,12 @@ mount RubyLLM::Agents::Engine => "/agents"
 | [Agent DSL](https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL) | All DSL options: model, temperature, params, caching, description |
 | [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) | Retries, fallbacks, circuit breakers, timeouts, reliability block |
 | [Budget Controls](https://github.com/adham90/ruby_llm-agents/wiki/Budget-Controls) | Spending limits, alerts, enforcement |
+| [Pricing](https://github.com/adham90/ruby_llm-agents/wiki/Pricing) | Multi-source pricing cascade, caching, configuration |
 | [Multi-Tenancy](https://github.com/adham90/ruby_llm-agents/wiki/Multi-Tenancy) | Per-tenant budgets, isolation, configuration |
 | [Async/Fiber](https://github.com/adham90/ruby_llm-agents/wiki/Async-Fiber) | Concurrent execution with Ruby fibers |
 | [Testing Agents](https://github.com/adham90/ruby_llm-agents/wiki/Testing-Agents) | RSpec patterns, mocking, dry_run mode |
 | [Error Handling](https://github.com/adham90/ruby_llm-agents/wiki/Error-Handling) | Error types, recovery patterns |
+| [Routing](https://github.com/adham90/ruby_llm-agents/wiki/Routing) | Message classification, routing DSL, inline classify |
 | [Embeddings](https://github.com/adham90/ruby_llm-agents/wiki/Embeddings) | Vector embeddings, batching, caching, preprocessing |
 | [Image Generation](https://github.com/adham90/ruby_llm-agents/wiki/Image-Generation) | Text-to-image, templates, pipelines, cost tracking |
 | [Dashboard](https://github.com/adham90/ruby_llm-agents/wiki/Dashboard) | Setup, authentication, analytics |

data/app/controllers/ruby_llm/agents/agents_controller.rb

@@ -50,7 +50,8 @@ module RubyLLM
           embedder: @agents.select { |a| a[:agent_type] == "embedder" },
           speaker: @agents.select { |a| a[:agent_type] == "speaker" },
           transcriber: @agents.select { |a| a[:agent_type] == "transcriber" },
-          image_generator: @agents.select { |a| a[:agent_type] == "image_generator" }
+          image_generator: @agents.select { |a| a[:agent_type] == "image_generator" },
+          router: @agents.select { |a| a[:agent_type] == "router" }
         }
 
         @agent_count = @agents.size
@@ -59,7 +60,7 @@ module RubyLLM
         Rails.logger.error("[RubyLLM::Agents] Error loading agents: #{e.message}")
         @agents = []
         @deleted_agents = []
-        @agents_by_type = {agent: [], embedder: [], speaker: [], transcriber: [], image_generator: []}
+        @agents_by_type = {agent: [], embedder: [], speaker: [], transcriber: [], image_generator: [], router: []}
         @agent_count = 0
         @deleted_count = 0
         @sort_params = {column: DEFAULT_AGENT_SORT_COLUMN, direction: DEFAULT_AGENT_SORT_DIRECTION}
@@ -85,8 +86,8 @@ module RubyLLM
 
         if @agent_class
           load_agent_config
-          # Only load circuit breaker status for base agents
-          load_circuit_breaker_status if @agent_type_kind == "agent"
+          # Load circuit breaker status for agents that support reliability
+          load_circuit_breaker_status if @agent_type_kind.in?(%w[agent router])
         end
       rescue => e
         Rails.logger.error("[RubyLLM::Agents] Error loading agent #{@agent_type}: #{e.message}")
@@ -207,6 +208,8 @@ module RubyLLM
           load_transcriber_config
         when "image_generator"
           load_image_generator_config
+        when "router"
+          load_router_config
         else
           load_base_agent_config
         end
@@ -291,6 +294,26 @@ module RubyLLM
         )
       end
 
+      # Loads configuration specific to Router agents
+      #
+      # @return [void]
+      def load_router_config
+        routes = safe_config_call(:routes) || {}
+        @config.merge!(
+          temperature: safe_config_call(:temperature),
+          timeout: safe_config_call(:timeout),
+          cache_enabled: safe_config_call(:cache_enabled?) || false,
+          cache_ttl: safe_config_call(:cache_ttl),
+          default_route: safe_config_call(:default_route_name),
+          routes: routes.transform_values { |v| v[:description] },
+          route_count: routes.size,
+          retries: safe_config_call(:retries),
+          fallback_models: safe_config_call(:fallback_models),
+          total_timeout: safe_config_call(:total_timeout),
+          circuit_breaker: safe_config_call(:circuit_breaker_config)
+        )
+      end
+
       # Safely calls a method on the agent class, returning nil on error
       #
       # @param method [Symbol] The method to call

data/app/services/ruby_llm/agents/agent_registry.rb

@@ -176,7 +176,7 @@ module RubyLLM
         # Detects the agent type from class hierarchy
         #
         # @param agent_class [Class, nil] The agent class
-        # @return [String] "agent", "embedder", "speaker", "transcriber", or "image_generator"
+        # @return [String] "agent", "embedder", "speaker", "transcriber", "image_generator", or "router"
         def detect_agent_type(agent_class)
           return "agent" unless agent_class
 
@@ -190,6 +190,8 @@ module RubyLLM
             "transcriber"
           elsif ancestors.include?("RubyLLM::Agents::ImageGenerator")
             "image_generator"
+          elsif agent_class.respond_to?(:routes) && agent_class.ancestors.any? { |a| a.name.to_s == "RubyLLM::Agents::Routing" }
+            "router"
           else
             "agent"
           end

data/app/views/ruby_llm/agents/agents/_config_router.html.erb

@@ -0,0 +1,110 @@
+<%# Configuration partial for Router agent types - grid layout %>
+<%
+  routes = config[:routes] || {}
+  default_route = config[:default_route] || :general
+  retries_config = config[:retries] || {}
+  fallback_models = Array(config[:fallback_models]).compact
+  has_retries = (retries_config[:max] || 0) > 0
+  has_fallbacks = fallback_models.any?
+  has_total_timeout = config[:total_timeout].present?
+  has_circuit_breaker = config[:circuit_breaker].present?
+  has_any_reliability = has_retries || has_fallbacks || has_total_timeout || has_circuit_breaker
+%>
+
+<div class="grid grid-cols-1 md:grid-cols-2 gap-x-8 gap-y-4 font-mono text-xs">
+  <!-- Basic -->
+  <div>
+    <span class="text-[10px] text-gray-400 dark:text-gray-600 uppercase tracking-wider">basic</span>
+    <div class="mt-1.5 space-y-0.5">
+      <div class="flex items-center gap-3 py-1">
+        <span class="w-20 text-gray-400 dark:text-gray-600">model</span>
+        <span class="text-gray-900 dark:text-gray-200"><%= config[:model] %></span>
+      </div>
+      <div class="flex items-center gap-3 py-1">
+        <span class="w-20 text-gray-400 dark:text-gray-600">temperature</span>
+        <span class="text-gray-900 dark:text-gray-200"><%= config[:temperature] %></span>
+      </div>
+      <div class="flex items-center gap-3 py-1">
+        <span class="w-20 text-gray-400 dark:text-gray-600">timeout</span>
+        <span class="text-gray-900 dark:text-gray-200"><%= config[:timeout] %>s</span>
+      </div>
+      <div class="flex items-center gap-3 py-1">
+        <span class="w-20 text-gray-400 dark:text-gray-600">cache</span>
+        <% if config[:cache_enabled] %>
+          <span class="text-green-500">enabled</span>
+          <span class="text-gray-400 dark:text-gray-600">(<%= config[:cache_ttl].inspect %>)</span>
+        <% else %>
+          <span class="text-gray-400 dark:text-gray-600">disabled</span>
+        <% end %>
+      </div>
+    </div>
+  </div>
+
+  <!-- Routes -->
+  <div>
+    <span class="text-[10px] text-gray-400 dark:text-gray-600 uppercase tracking-wider">routes (<%= routes.size %>)</span>
+    <% if routes.any? %>
+      <div class="mt-1.5 space-y-0.5">
+        <% routes.each do |name, description| %>
+          <div class="flex items-center gap-2 py-1">
+            <span class="w-1.5 h-1.5 rounded-full flex-shrink-0 <%= name.to_sym == default_route ? 'bg-cyan-500' : 'bg-gray-400' %>"></span>
+            <span class="w-24 text-gray-900 dark:text-gray-200 truncate"><%= name %></span>
+            <span class="text-gray-400 dark:text-gray-600 truncate"><%= description %></span>
+          </div>
+        <% end %>
+        <div class="flex items-center gap-2 py-1 mt-0.5">
+          <span class="w-1.5 flex-shrink-0"></span>
+          <span class="text-[10px] text-gray-400 dark:text-gray-600">default: <span class="text-cyan-600 dark:text-cyan-400"><%= default_route %></span></span>
+        </div>
+      </div>
+    <% else %>
+      <div class="mt-1 py-1 text-gray-400 dark:text-gray-600">no routes defined</div>
+    <% end %>
+  </div>
+
+  <% if has_any_reliability %>
+    <!-- Reliability -->
+    <div class="md:col-span-2">
+      <span class="text-[10px] text-gray-400 dark:text-gray-600 uppercase tracking-wider">reliability</span>
+      <div class="mt-1.5 flex flex-wrap gap-x-8 gap-y-0.5">
+        <div class="flex items-center gap-2 py-1">
+          <span class="w-1.5 h-1.5 rounded-full flex-shrink-0 <%= has_retries ? 'bg-green-500' : 'bg-gray-400' %>"></span>
+          <span class="w-16 text-gray-400 dark:text-gray-600">retries</span>
+          <% if has_retries %>
+            <span class="text-gray-900 dark:text-gray-200"><%= retries_config[:max] %> max</span>
+          <% else %>
+            <span class="text-gray-400 dark:text-gray-600">&mdash;</span>
+          <% end %>
+        </div>
+        <div class="flex items-center gap-2 py-1">
+          <span class="w-1.5 h-1.5 rounded-full flex-shrink-0 <%= has_fallbacks ? 'bg-green-500' : 'bg-gray-400' %>"></span>
+          <span class="w-16 text-gray-400 dark:text-gray-600">fallbacks</span>
+          <% if has_fallbacks %>
+            <span class="text-gray-900 dark:text-gray-200 truncate"><%= fallback_models.join(" → ") %></span>
+          <% else %>
+            <span class="text-gray-400 dark:text-gray-600">&mdash;</span>
+          <% end %>
+        </div>
+        <div class="flex items-center gap-2 py-1">
+          <span class="w-1.5 h-1.5 rounded-full flex-shrink-0 <%= has_total_timeout ? 'bg-green-500' : 'bg-gray-400' %>"></span>
+          <span class="w-16 text-gray-400 dark:text-gray-600">timeout</span>
+          <% if has_total_timeout %>
+            <span class="text-gray-900 dark:text-gray-200"><%= config[:total_timeout] %>s total</span>
+          <% else %>
+            <span class="text-gray-400 dark:text-gray-600">&mdash;</span>
+          <% end %>
+        </div>
+        <div class="flex items-center gap-2 py-1">
+          <span class="w-1.5 h-1.5 rounded-full flex-shrink-0 <%= has_circuit_breaker ? 'bg-green-500' : 'bg-gray-400' %>"></span>
+          <span class="w-16 text-gray-400 dark:text-gray-600">breaker</span>
+          <% if has_circuit_breaker %>
+            <% cb = config[:circuit_breaker] %>
+            <span class="text-gray-900 dark:text-gray-200"><%= cb[:errors] %>/<%= cb[:within] %>s</span>
+          <% else %>
+            <span class="text-gray-400 dark:text-gray-600">&mdash;</span>
+          <% end %>
+        </div>
+      </div>
+    </div>
+  <% end %>
+</div>

data/app/views/ruby_llm/agents/agents/index.html.erb

@@ -17,6 +17,7 @@
     embedder: <%= @agents_by_type[:embedder].size %>,
     audio: <%= audio_count %>,
     image_generator: <%= @agents_by_type[:image_generator].size %>,
+    router: <%= @agents_by_type[:router].size %>,
     deleted: <%= @deleted_count %>
   },
   get currentCount() {
@@ -62,6 +63,11 @@
                 :class="activeSubTab === 'image_generator' ? 'text-gray-900 dark:text-gray-100' : 'text-gray-400 dark:text-gray-500 hover:text-gray-700 dark:hover:text-gray-300'"
                 class="px-2 py-0.5">image</button>
       <% end %>
+      <% if @agents_by_type[:router].size > 0 %>
+        <button type="button" @click="activeSubTab = 'router'; updateUrl()"
+                :class="activeSubTab === 'router' ? 'text-gray-900 dark:text-gray-100' : 'text-gray-400 dark:text-gray-500 hover:text-gray-700 dark:hover:text-gray-300'"
+                class="px-2 py-0.5">routers</button>
+      <% end %>
       <% if @deleted_count > 0 %>
         <button type="button" @click="activeSubTab = 'deleted'; updateUrl()"
                 :class="activeSubTab === 'deleted' ? 'text-gray-900 dark:text-gray-100' : 'text-gray-400 dark:text-gray-500 hover:text-gray-700 dark:hover:text-gray-300'"

data/app/views/ruby_llm/agents/executions/show.html.erb

@@ -21,6 +21,7 @@
     secondary_badges << { label: @execution.finish_reason, css: finish_css }
   end
   secondary_badges << { label: "rate limited", css: "badge-orange" } if @execution.respond_to?(:rate_limited?) && @execution.rate_limited?
+  secondary_badges << { label: "no pricing", css: "badge-orange" } if @execution.metadata&.dig("pricing_warning")
 %>
 <div class="flex flex-wrap items-center gap-3 mb-1.5">
   <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono"><%= @execution.agent_type.gsub(/Agent$/, '') %></span>
@@ -47,6 +48,15 @@
   <%= time_ago_in_words(@execution.created_at) %> ago
 </div>
 
+<!-- Pricing warning -->
+<% if @execution.metadata&.dig("pricing_warning") %>
+  <div class="flex items-center gap-2 bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-800 rounded px-3 py-2 mb-2">
+    <span class="text-amber-600 dark:text-amber-400 text-xs font-mono">
+      &#9888; <%= @execution.metadata["pricing_warning"] %>
+    </span>
+  </div>
+<% end %>
+
 <!-- Stats inline row -->
 <div class="flex flex-wrap items-center gap-x-4 gap-y-1 font-mono text-xs text-gray-400 dark:text-gray-500 mb-2">
   <span><span class="text-gray-800 dark:text-gray-200"><%= number_to_human_short(@execution.duration_ms || 0) %>ms</span> duration</span>

data/app/views/ruby_llm/agents/shared/_agent_type_badge.html.erb

@@ -50,6 +50,14 @@
         text: "text-pink-700 dark:text-pink-300",
         icon_char: "🎨"
       }
+    when "router"
+      {
+        icon: "router",
+        label: "Router",
+        bg: "bg-cyan-100 dark:bg-cyan-500/20",
+        text: "text-cyan-700 dark:text-cyan-300",
+        icon_char: "🔀"
+      }
     else
       {
         icon: "question",

data/lib/ruby_llm/agents/audio/speaker.rb

@@ -446,7 +446,7 @@ module RubyLLM
 
         # Warn: style used on model that doesn't support it
         vs = self.class.voice_settings_config
-        if vs && vs.style_value && vs.style_value > 0 && model["can_use_style"] != true
+        if vs&.style_value && vs.style_value > 0 && model["can_use_style"] != true
           warn "[RubyLLM::Agents] Model '#{model_id}' does not support the 'style' voice setting. It will be ignored."
         end
       rescue ConfigurationError

data/lib/ruby_llm/agents/audio/transcriber.rb

@@ -2,6 +2,7 @@
 
 require "digest"
 require_relative "../results/transcription_result"
+require_relative "transcription_pricing"
 
 module RubyLLM
   module Agents
@@ -318,6 +319,12 @@ module RubyLLM
         context.output_tokens = 0
         context.total_cost = calculate_cost(raw_result)
 
+        # Store pricing warning if cost calculation returned nil
+        if @pricing_warning
+          context[:pricing_warning] = @pricing_warning
+          Rails.logger.warn(@pricing_warning) if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        end
+
         # Store transcription-specific metadata for execution tracking
         context[:language] = resolved_language if resolved_language
         context[:detected_language] = raw_result[:language] if raw_result[:language]
@@ -615,30 +622,34 @@ module RubyLLM
       # Calculates cost for transcription
       #
       # @param raw_result [Hash] Raw transcription result
-      # @return [Float] Cost in USD
+      # @return [Float] Cost in USD (0 if no pricing found)
       def calculate_cost(raw_result)
-        # Get duration in minutes
-        duration_minutes = raw_result[:duration] ? raw_result[:duration] / 60.0 : 0
+        @pricing_warning = nil
 
-        # Check if response has cost info
+        # Check if response has cost info from the API
         if raw_result[:raw_response].respond_to?(:cost) && raw_result[:raw_response].cost
           return raw_result[:raw_response].cost
         end
 
-        # Estimate based on model and duration
+        # Delegate to TranscriptionPricing (2-tier: LiteLLM + user config)
         model = raw_result[:model].to_s
-        price_per_minute = case model
-        when /whisper-1/
-          0.006
-        when /gpt-4o-transcribe/
-          0.01
-        when /gpt-4o-mini-transcribe/
-          0.005
-        else
-          0.006 # Default to whisper pricing
+        duration = raw_result[:duration] || 0
+
+        cost = Audio::TranscriptionPricing.calculate_cost(
+          model_id: model,
+          duration_seconds: duration
+        )
+
+        if cost.nil?
+          @pricing_warning = "[RubyLLM::Agents] No pricing found for transcription model '#{model}'. " \
+            "Cost recorded as $0. Add pricing to your config:\n" \
+            "  RubyLLM::Agents.configure do |c|\n" \
+            "    c.transcription_model_pricing = { \"#{model}\" => 0.006 }  # price per minute\n" \
+            "  end"
+          return 0
         end
 
-        duration_minutes * price_per_minute
+        cost
       end
 
       # Resolves the model to use

data/lib/ruby_llm/agents/audio/transcription_pricing.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require_relative "../pricing/data_store"
+require_relative "../pricing/ruby_llm_adapter"
+require_relative "../pricing/litellm_adapter"
+require_relative "../pricing/portkey_adapter"
+require_relative "../pricing/openrouter_adapter"
+require_relative "../pricing/helicone_adapter"
+require_relative "../pricing/llmpricing_adapter"
+
+module RubyLLM
+  module Agents
+    module Audio
+      # Dynamic pricing resolution for audio transcription models.
+      #
+      # Cascades through multiple pricing sources to maximize coverage:
+      # 1. User config (instant, always wins)
+      # 2. RubyLLM gem (local, no HTTP, already a dependency)
+      # 3. LiteLLM (bulk, most comprehensive for transcription)
+      # 4. Portkey AI (per-model, good transcription coverage)
+      # 5. OpenRouter (bulk, audio-capable chat models only)
+      # 6. Helicone (text LLM only — pass-through, future-proof)
+      # 7. LLM Pricing AI (text LLM only — pass-through, future-proof)
+      #
+      # When no pricing is found, methods return nil to signal the caller
+      # should warn the user with actionable configuration instructions.
+      #
+      # All prices are per minute of audio.
+      #
+      # @example Get cost for a transcription
+      #   TranscriptionPricing.calculate_cost(model_id: "whisper-1", duration_seconds: 120)
+      #   # => 0.012 (or nil if no pricing found)
+      #
+      # @example User-configured pricing
+      #   RubyLLM::Agents.configure do |c|
+      #     c.transcription_model_pricing = { "whisper-1" => 0.006 }
+      #   end
+      #
+      module TranscriptionPricing
+        extend self
+
+        LITELLM_PRICING_URL = Pricing::DataStore::LITELLM_URL
+
+        SOURCES = [:config, :ruby_llm, :litellm, :portkey, :openrouter, :helicone, :llmpricing].freeze
+
+        # Calculate total cost for a transcription operation
+        #
+        # @param model_id [String] The model identifier
+        # @param duration_seconds [Numeric] Duration of audio in seconds
+        # @return [Float, nil] Total cost in USD, or nil if no pricing found
+        def calculate_cost(model_id:, duration_seconds:)
+          price = cost_per_minute(model_id)
+          return nil unless price
+
+          duration_minutes = duration_seconds / 60.0
+          (duration_minutes * price).round(6)
+        end
+
+        # Get cost per minute for a transcription model
+        #
+        # @param model_id [String] Model identifier
+        # @return [Float, nil] Cost per minute in USD, or nil if not found
+        def cost_per_minute(model_id)
+          SOURCES.each do |source|
+            price = send(:"from_#{source}", model_id)
+            return price if price
+          end
+          nil
+        end
+
+        # Check whether pricing is available for a model
+        #
+        # @param model_id [String] Model identifier
+        # @return [Boolean] true if pricing is available
+        def pricing_found?(model_id)
+          !cost_per_minute(model_id).nil?
+        end
+
+        # Force refresh of cached pricing data
+        def refresh!
+          Pricing::DataStore.refresh!
+        end
+
+        # Expose all known pricing for debugging/dashboard
+        #
+        # @return [Hash] Pricing from all tiers
+        def all_pricing
+          {
+            ruby_llm: {},  # local gem, per-model lookup
+            litellm: litellm_transcription_models,
+            portkey: {},  # per-model, populated on demand
+            openrouter: {},  # no dedicated transcription models
+            helicone: {},  # no transcription models
+            configured: config.transcription_model_pricing || {}
+          }
+        end
+
+        private
+
+        # ============================================================
+        # Tier 1: User configuration (highest priority)
+        # ============================================================
+
+        def from_config(model_id)
+          table = config.transcription_model_pricing
+          return nil unless table.is_a?(Hash) && !table.empty?
+
+          normalized = normalize_model_id(model_id)
+
+          price = table[model_id] || table[normalized] ||
+            table[model_id.to_sym] || table[normalized.to_sym]
+
+          price if price.is_a?(Numeric)
+        end
+
+        # ============================================================
+        # Tier 2: RubyLLM gem (local, no HTTP)
+        # ============================================================
+
+        def from_ruby_llm(model_id)
+          data = Pricing::RubyLLMAdapter.find_model(model_id)
+          return nil unless data
+
+          extract_per_minute(data)
+        end
+
+        # ============================================================
+        # Tier 3: LiteLLM
+        # ============================================================
+
+        def from_litellm(model_id)
+          data = Pricing::LiteLLMAdapter.find_model(model_id)
+          return nil unless data
+
+          extract_per_minute(data)
+        end
+
+        # ============================================================
+        # Tier 4: Portkey AI
+        # ============================================================
+
+        def from_portkey(model_id)
+          data = Pricing::PortkeyAdapter.find_model(model_id)
+          return nil unless data
+
+          extract_per_minute(data)
+        end
+
+        # ============================================================
+        # Tier 5: OpenRouter (audio-capable chat models only)
+        # ============================================================
+
+        def from_openrouter(model_id)
+          data = Pricing::OpenRouterAdapter.find_model(model_id)
+          return nil unless data
+
+          extract_per_minute(data)
+        end
+
+        # ============================================================
+        # Tier 6: Helicone (text LLM only — future-proof)
+        # ============================================================
+
+        def from_helicone(model_id)
+          data = Pricing::HeliconeAdapter.find_model(model_id)
+          return nil unless data
+
+          extract_per_minute(data)
+        end
+
+        # ============================================================
+        # Tier 7: LLM Pricing AI (text LLM only — future-proof)
+        # ============================================================
+
+        def from_llmpricing(model_id)
+          data = Pricing::LLMPricingAdapter.find_model(model_id)
+          return nil unless data
+
+          extract_per_minute(data)
+        end
+
+        # ============================================================
+        # Price extraction
+        # ============================================================
+
+        def extract_per_minute(data)
+          # Per-second pricing (most common for transcription: whisper-1, etc.)
+          if data[:input_cost_per_second]
+            return (data[:input_cost_per_second] * 60).round(6)
+          end
+
+          # Per-audio-token pricing (GPT-4o-transcribe models)
+          # ~25 audio tokens/second = 1500 tokens/minute
+          if data[:input_cost_per_audio_token]
+            return (data[:input_cost_per_audio_token] * 1500).round(6)
+          end
+
+          nil
+        end
+
+        def litellm_transcription_models
+          data = Pricing::DataStore.litellm_data
+          return {} unless data.is_a?(Hash)
+
+          data.select do |key, value|
+            value.is_a?(Hash) && (
+              value["mode"] == "audio_transcription" ||
+              value["input_cost_per_second"] ||
+              key.to_s.match?(/whisper|transcri/i)
+            )
+          end
+        end
+
+        def normalize_model_id(model_id)
+          model_id.to_s.downcase
+            .gsub(/[^a-z0-9._-]/, "-").squeeze("-")
+            .gsub(/^-|-$/, "")
+        end
+
+        def config
+          RubyLLM::Agents.configuration
+        end
+      end
+    end
+  end
+end