ruby_llm-agents 3.3.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 463487c17c50bf1496a30c9eea51dab3c334a17010853da97da5624a6cf564b5
-  data.tar.gz: 470a6666266d17dc8190f5118eec0c5f674fb51bae8b368d8713ea65d1882025
+  metadata.gz: 4cb913b70bd04950b91cc665ef9e2af84aa009618dffb7072e9d6b8ae389bc77
+  data.tar.gz: 479066023ed864ee78c317c37f64e92c8fb2b503215ac0280e097a14d9ba2ba7
 SHA512:
-  metadata.gz: b1e2d4688dfc294c3b94c95df084a248fa25fbcd7d99910f31f72b85138bf37a392a8b350462ee341d5d209674b844a9d2692a177db30845857a586fa77ce3bc
-  data.tar.gz: 50130237011f12c808a073d55b9083ce8449f8e0ddf8dd800c13134104f48233ea4f0fac3ddcbcc9a8b45b91814f67db5c57632dd6d54930c1ffd19fda825e96
+  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,7 +180,8 @@ 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) |
-| **Audio** | Text-to-speech (OpenAI, ElevenLabs), speech-to-text, dashboard audio playback | [Audio](https://github.com/adham90/ruby_llm-agents/wiki/Audio) |
+| **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) |
 
 ## Quick Start
@@ -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/elevenlabs/model_registry.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module RubyLLM
+  module Agents
+    module Audio
+      module ElevenLabs
+        # Fetches and caches ElevenLabs model data from the /v1/models API.
+        #
+        # Used for:
+        # - Dynamic cost calculation via character_cost_multiplier
+        # - Model validation (TTS vs STS capability)
+        # - Capability awareness (style, speaker_boost, max chars, languages)
+        #
+        # @example Check if a model supports TTS
+        #   ElevenLabs::ModelRegistry.tts_model?("eleven_v3") # => true
+        #   ElevenLabs::ModelRegistry.tts_model?("eleven_english_sts_v2") # => false
+        #
+        # @example Get cost multiplier
+        #   ElevenLabs::ModelRegistry.cost_multiplier("eleven_flash_v2_5") # => 0.5
+        #
+        module ModelRegistry
+          extend self
+
+          # Returns all models from the ElevenLabs API (cached)
+          #
+          # @return [Array<Hash>] Array of model hashes
+          def models
+            @mutex ||= Mutex.new
+            @mutex.synchronize do
+              if @models && !cache_expired?
+                return @models
+              end
+
+              @models = fetch_models
+              @fetched_at = Time.now
+              @models
+            end
+          end
+
+          # Find a specific model by ID
+          #
+          # @param model_id [String] The model identifier
+          # @return [Hash, nil] Model hash or nil if not found
+          def find(model_id)
+            models.find { |m| m["model_id"] == model_id.to_s }
+          end
+
+          # Check if model supports text-to-speech
+          #
+          # @param model_id [String] The model identifier
+          # @return [Boolean]
+          def tts_model?(model_id)
+            model = find(model_id)
+            return false unless model
+
+            model["can_do_text_to_speech"] == true
+          end
+
+          # Get character_cost_multiplier for a model
+          #
+          # @param model_id [String] The model identifier
+          # @return [Float] Cost multiplier (defaults to 1.0 for unknown models)
+          def cost_multiplier(model_id)
+            model = find(model_id)
+            model&.dig("model_rates", "character_cost_multiplier") || 1.0
+          end
+
+          # Get max characters per request for a model
+          #
+          # @param model_id [String] The model identifier
+          # @return [Integer, nil] Max characters or nil if unknown
+          def max_characters(model_id)
+            model = find(model_id)
+            model&.dig("maximum_text_length_per_request")
+          end
+
+          # Get supported language IDs for a model
+          #
+          # @param model_id [String] The model identifier
+          # @return [Array<String>] Language IDs (e.g. ["en", "es", "ja"])
+          def languages(model_id)
+            model = find(model_id)
+            model&.dig("languages")&.map { |l| l["language_id"] } || []
+          end
+
+          # Check if model supports the style voice setting
+          #
+          # @param model_id [String] The model identifier
+          # @return [Boolean]
+          def supports_style?(model_id)
+            find(model_id)&.dig("can_use_style") == true
+          end
+
+          # Check if model supports the speaker_boost setting
+          #
+          # @param model_id [String] The model identifier
+          # @return [Boolean]
+          def supports_speaker_boost?(model_id)
+            find(model_id)&.dig("can_use_speaker_boost") == true
+          end
+
+          # Check if model supports voice conversion (speech-to-speech)
+          # Used by VoiceConverter agent (see plans/elevenlabs_voice_converter.md)
+          #
+          # @param model_id [String] The model identifier
+          # @return [Boolean]
+          def voice_conversion_model?(model_id)
+            model = find(model_id)
+            return false unless model
+
+            model["can_do_voice_conversion"] == true
+          end
+
+          # Force refresh the cache
+          #
+          # @return [Array<Hash>] Fresh model data
+          def refresh!
+            @mutex ||= Mutex.new
+            @mutex.synchronize do
+              @models = nil
+              @fetched_at = nil
+            end
+            models
+          end
+
+          # Clear cache without re-fetching (useful for tests)
+          #
+          # @return [void]
+          def clear_cache!
+            @mutex ||= Mutex.new
+            @mutex.synchronize do
+              @models = nil
+              @fetched_at = nil
+            end
+          end
+
+          private
+
+          def fetch_models
+            return [] unless api_key
+
+            response = connection.get("/v1/models")
+
+            if response.success?
+              parsed = JSON.parse(response.body)
+              parsed.is_a?(Array) ? parsed : []
+            else
+              warn "[RubyLLM::Agents] ElevenLabs /v1/models returned HTTP #{response.status}"
+              @models || []
+            end
+          rescue Faraday::Error, JSON::ParserError => e
+            warn "[RubyLLM::Agents] Failed to fetch ElevenLabs models: #{e.message}"
+            @models || []
+          end
+
+          def cache_expired?
+            return true unless @fetched_at
+
+            ttl = RubyLLM::Agents.configuration.elevenlabs_models_cache_ttl || 21_600
+            Time.now - @fetched_at > ttl
+          end
+
+          def api_key
+            RubyLLM::Agents.configuration.elevenlabs_api_key
+          end
+
+          def api_base
+            base = RubyLLM::Agents.configuration.elevenlabs_api_base
+            (base && !base.empty?) ? base : "https://api.elevenlabs.io"
+          end
+
+          def connection
+            Faraday.new(url: api_base) do |f|
+              f.headers["xi-api-key"] = api_key
+              f.adapter Faraday.default_adapter
+              f.options.timeout = 10
+              f.options.open_timeout = 5
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,7 @@ require "digest"
 require_relative "../results/speech_result"
 require_relative "speech_client"
 require_relative "speech_pricing"
+require_relative "elevenlabs/model_registry"
 
 module RubyLLM
   module Agents
@@ -409,6 +410,7 @@ module RubyLLM
 
       # Executes speech synthesis
       def execute_speech(processed_text)
+        validate_elevenlabs_model!(processed_text)
         speak_options = build_speak_options
 
         if streaming_enabled? && @streaming_block
@@ -418,6 +420,42 @@ module RubyLLM
         end
       end
 
+      # Validates ElevenLabs model capabilities before calling the API.
+      # Raises on hard errors (non-TTS model), warns on soft issues.
+      def validate_elevenlabs_model!(text)
+        return unless resolved_provider == :elevenlabs
+        return unless defined?(Audio::ElevenLabs::ModelRegistry)
+
+        model_id = resolved_model
+        model = Audio::ElevenLabs::ModelRegistry.find(model_id)
+        return unless model # Unknown model — skip validation
+
+        # Hard error: model doesn't support TTS at all
+        unless model["can_do_text_to_speech"] == true
+          raise ConfigurationError,
+            "ElevenLabs model '#{model_id}' does not support text-to-speech. " \
+            "It may be a speech-to-speech model. Use a TTS-capable model like 'eleven_v3'."
+        end
+
+        # Warn: text exceeds model's max character limit
+        max_chars = model["maximum_text_length_per_request"]
+        if max_chars && text.length > max_chars
+          warn "[RubyLLM::Agents] Text length (#{text.length}) exceeds " \
+               "#{model_id} max of #{max_chars} characters. The API may truncate or reject it."
+        end
+
+        # Warn: style used on model that doesn't support it
+        vs = self.class.voice_settings_config
+        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
+        raise
+      rescue => e
+        # Don't block speech on validation errors
+        warn "[RubyLLM::Agents] ElevenLabs model validation failed: #{e.message}"
+      end
+
       # Executes standard (non-streaming) speech synthesis
       def execute_standard_speech(text, options)
         response = speech_client.speak(

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

@@ -2,6 +2,7 @@
 
 require "faraday"
 require "json"
+require "set"
 
 module RubyLLM
   module Agents
@@ -266,14 +267,37 @@ module RubyLLM
           body
         end
 
+        # Convenience mapping: simple symbol → ElevenLabs native format string
         ELEVENLABS_FORMAT_MAP = {
           "mp3" => "mp3_44100_128",
-          "pcm" => "pcm_44100",
+          "wav" => "wav_44100",
+          "ogg" => "mp3_44100_128",   # ElevenLabs doesn't support ogg; fallback to mp3
+          "pcm" => "pcm_24000",
+          "opus" => "opus_48000_128",
+          "flac" => "mp3_44100_128",  # ElevenLabs doesn't support flac; fallback to mp3
+          "aac" => "mp3_44100_128",   # ElevenLabs doesn't support aac; fallback to mp3
+          "alaw" => "alaw_8000",
           "ulaw" => "ulaw_8000"
         }.freeze
 
+        # All valid ElevenLabs native format strings (pass-through)
+        ELEVENLABS_NATIVE_FORMATS = Set.new(%w[
+          mp3_22050_32 mp3_24000_48 mp3_44100_32 mp3_44100_64
+          mp3_44100_96 mp3_44100_128 mp3_44100_192
+          pcm_8000 pcm_16000 pcm_22050 pcm_24000 pcm_32000 pcm_44100 pcm_48000
+          wav_8000 wav_16000 wav_22050 wav_24000 wav_32000 wav_44100 wav_48000
+          opus_48000_32 opus_48000_64 opus_48000_96 opus_48000_128 opus_48000_192
+          alaw_8000 ulaw_8000
+        ]).freeze
+
         def elevenlabs_output_format(format)
-          ELEVENLABS_FORMAT_MAP[format.to_s] || "mp3_44100_128"
+          format_str = format.to_s
+
+          # Pass through native ElevenLabs format strings directly
+          return format_str if ELEVENLABS_NATIVE_FORMATS.include?(format_str)
+
+          # Map simple symbols to native formats
+          ELEVENLABS_FORMAT_MAP[format_str] || "mp3_44100_128"
         end
 
         def elevenlabs_connection