ruby_llm-agents 3.2.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8c4a83ecc9e39e7df7243b98a51d1c249a963f3a1f96551ebefae13becb50c5
-  data.tar.gz: d042bda1737b7593187896e879b3065cc855e990e1406410e99d1d853819f3a9
+  metadata.gz: 82355e2a179ddaf2f5003b2cbd972f373b2ca49cdcc2847535aec89fb18ed046
+  data.tar.gz: '09656de02af43adafdfe2615d1bfcb67aee76602fd0699d0f739eda731f29d8d'
 SHA512:
-  metadata.gz: 78b6fa31a8a656c36e0bb51f6e7a405101e90f47afc3ca35f87c392878b6a2d986b2b275c6424826ffb6b5d4bfb059f4632e8976aa5b2a473eab540619bd18cb
-  data.tar.gz: 3d5890ea864aea3531e96571b6010c9fdcedc5a15e8966c7974138cde0ebaec89a771e33fd20e3fd2d5097a1ecfc398236d833f9852f046fd3b1f720eaf7fb6e
+  metadata.gz: a5c8b20da41f0f73b8fdbffb809cecc726f1e7e6030d8351c5b994c58192b8d18da7693fa8fadec603f8dfb29ab7dd40907877600f58af185ab9d5542a884dcf
+  data.tar.gz: b6c0c90038a87f2824ff52b0bedd901528e291748a18caff4fd2df403affd351bf7cdf05db3042e6daae05d602c672f90a9a97434e6f54f9834c337ebae1a607

data/README.md

@@ -135,7 +135,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) |
-| **Audio** | Text-to-speech (OpenAI, ElevenLabs) and speech-to-text with cost tracking | [Audio](https://github.com/adham90/ruby_llm-agents/wiki/Audio) |
+| **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

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

@@ -0,0 +1,57 @@
+<%
+  response = @execution.response || {}
+  audio_src = response["audio_url"] || response[:audio_url] ||
+              response["audio_data_uri"] || response[:audio_data_uri]
+  audio_format = response["format"] || response[:format] ||
+                 @execution.metadata&.dig("audio_format")
+  audio_duration = response["duration"] || response[:duration] ||
+                   @execution.metadata&.dig("audio_duration_seconds")
+  audio_file_size = response["file_size"] || response[:file_size] ||
+                    @execution.metadata&.dig("audio_file_size_bytes")
+  audio_voice = response["voice_id"] || response[:voice_id] ||
+                @execution.metadata&.dig("voice_id")
+  audio_provider = response["provider"] || response[:provider] ||
+                   @execution.metadata&.dig("audio_provider")
+  audio_characters = @execution.metadata&.dig("audio_characters")
+%>
+
+<div class="flex items-center gap-3 mt-6 mb-3">
+  <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">audio</span>
+  <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
+</div>
+
+<% if audio_src.present? %>
+  <div class="mb-3">
+    <audio controls preload="metadata" class="w-full max-w-lg" style="height: 36px;">
+      <source src="<%= audio_src %>">
+      Your browser does not support the audio element.
+    </audio>
+  </div>
+<% end %>
+
+<div class="flex flex-wrap items-center gap-x-4 gap-y-1 font-mono text-xs text-gray-400 dark:text-gray-500">
+  <% if audio_duration.present? %>
+    <span><span class="text-gray-800 dark:text-gray-200"><%= audio_duration.is_a?(Numeric) ? "#{audio_duration.round(1)}s" : audio_duration %></span> duration</span>
+  <% end %>
+  <% if audio_format.present? %>
+    <span><span class="text-gray-800 dark:text-gray-200"><%= audio_format %></span> format</span>
+  <% end %>
+  <% if audio_file_size.present? %>
+    <span><span class="text-gray-800 dark:text-gray-200"><%= number_to_human_size(audio_file_size) %></span> size</span>
+  <% end %>
+  <% if audio_voice.present? %>
+    <span><span class="text-gray-800 dark:text-gray-200"><%= audio_voice %></span> voice</span>
+  <% end %>
+  <% if audio_provider.present? %>
+    <span><span class="text-gray-800 dark:text-gray-200"><%= audio_provider %></span> provider</span>
+  <% end %>
+  <% if audio_characters.present? %>
+    <span><span class="text-gray-800 dark:text-gray-200"><%= number_to_human_short(audio_characters) %></span> characters</span>
+  <% end %>
+</div>
+
+<% if audio_src.blank? %>
+  <p class="text-xs text-gray-400 dark:text-gray-600 font-mono mt-2 italic">
+    No audio data stored. Enable <code class="text-gray-500 dark:text-gray-400">persist_audio_data</code> in config to play back Speaker audio here.
+  </p>
+<% end %>

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

@@ -57,6 +57,14 @@
   <% end %>
 </div>
 
+<!-- ── audio player ──────────────────── -->
+<% if @execution.agent_type.to_s.match?(/Speaker|Narrator|Transcriber/i) ||
+      @execution.metadata&.dig("audio_duration_seconds").present? ||
+      @execution.response&.dig("audio_data_uri").present? ||
+      @execution.response&.dig("audio_url").present? %>
+  <%= render "ruby_llm/agents/executions/audio_player" %>
+<% end %>
+
 <!-- ── tokens ──────────────────────── -->
 <%
   input_tokens = @execution.input_tokens || 0

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/active_storage_support.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Speaker
+      # ActiveStorage integration for speakers
+      #
+      # Provides convenience methods for generating audio and directly
+      # attaching it to ActiveStorage attachments.
+      #
+      # @example Attaching to a model
+      #   class Article < ApplicationRecord
+      #     has_one_attached :narration
+      #   end
+      #
+      #   class ArticleNarrator < RubyLLM::Agents::Speaker
+      #     include RubyLLM::Agents::Speaker::ActiveStorageSupport
+      #
+      #     provider :openai
+      #     model 'tts-1-hd'
+      #     voice 'nova'
+      #   end
+      #
+      #   article = Article.find(1)
+      #   result = ArticleNarrator.speak_and_attach(
+      #     text: article.body,
+      #     record: article,
+      #     attachment_name: :narration
+      #   )
+      #
+      module ActiveStorageSupport
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Generate audio and attach it to a record
+          #
+          # @param text [String] Text to convert to speech
+          # @param record [ActiveRecord::Base] The record to attach to
+          # @param attachment_name [Symbol] Name of the attachment (e.g., :narration)
+          # @param options [Hash] Additional options for generation
+          # @return [SpeechResult] The speech result with audio_url set
+          def speak_and_attach(text:, record:, attachment_name:, **options)
+            result = call(text: text, **options)
+
+            return result unless result.success?
+
+            attach_audio_to_record(result, record, attachment_name, options)
+
+            result
+          end
+
+          private
+
+          def attach_audio_to_record(result, record, attachment_name, options)
+            attachment = record.public_send(attachment_name)
+            filename = options[:filename] || generate_audio_filename(result)
+
+            attachment.attach(
+              io: StringIO.new(result.audio),
+              filename: filename,
+              content_type: result.content_type
+            )
+
+            result.audio_key = attachment.blob.key if attachment.respond_to?(:blob) && attachment.blob
+            result.audio_url = blob_url(attachment) if attachment.respond_to?(:blob) && attachment.blob
+          end
+
+          def blob_url(attachment)
+            if attachment.blob.respond_to?(:url)
+              attachment.blob.url
+            elsif attachment.blob.respond_to?(:service_url)
+              attachment.blob.service_url
+            end
+          rescue => _e
+            nil
+          end
+
+          def generate_audio_filename(result)
+            timestamp = Time.current.to_i
+            ext = result.format || :mp3
+            "speech_#{timestamp}.#{ext}"
+          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
@@ -336,6 +337,14 @@ module RubyLLM
         context.output_tokens = 0
         context.total_cost = calculate_cost(result)
 
+        # Store audio-specific metadata for execution tracking
+        context[:provider] = result[:provider].to_s
+        context[:voice_id] = (resolved_voice_id || resolved_voice).to_s
+        context[:characters] = result[:characters]
+        context[:output_format] = result[:format].to_s
+        context[:file_size] = result[:audio]&.bytesize
+        context[:audio_duration_seconds] = result[:duration] if result[:duration]
+
         # Build final result
         context.output = build_result(
           result,
@@ -401,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
@@ -410,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 && 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(
@@ -559,3 +605,5 @@ module RubyLLM
     end
   end
 end
+
+require_relative "speaker/active_storage_support"

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

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

@@ -8,10 +8,11 @@ module RubyLLM
     module Audio
       # Dynamic pricing resolution for text-to-speech models.
       #
-      # Uses the same three-tier strategy as ImageGenerator::Pricing:
+      # Uses a four-tier pricing cascade:
       # 1. LiteLLM JSON (primary) - future-proof, auto-updating
       # 2. Configurable pricing table - user overrides via config.tts_model_pricing
-      # 3. Hardcoded fallbacks - per-model defaults
+      # 3. ElevenLabs API - dynamic multiplier × base rate from /v1/models
+      # 4. Hardcoded fallbacks - per-model defaults
       #
       # All prices are per 1,000 characters.
       #
@@ -50,14 +51,22 @@ module RubyLLM
         # @param model_id [String] Model identifier
         # @return [Float] Cost per 1K characters in USD
         def cost_per_1k_characters(provider, model_id)
+          # Tier 1: LiteLLM
           if (litellm_price = from_litellm(model_id))
             return litellm_price
           end
 
+          # Tier 2: User config overrides
           if (config_price = from_config(model_id))
             return config_price
           end
 
+          # Tier 3: ElevenLabs API multiplier × base rate
+          if provider == :elevenlabs && (api_price = from_elevenlabs_api(model_id))
+            return api_price
+          end
+
+          # Tier 4: Hardcoded fallbacks
           fallback_price(provider, model_id)
         end
 
@@ -73,6 +82,7 @@ module RubyLLM
           {
             litellm: litellm_tts_models,
             configured: config.tts_model_pricing || {},
+            elevenlabs_api: elevenlabs_api_pricing,
             fallbacks: fallback_pricing_table
           }
         end
@@ -190,6 +200,19 @@ module RubyLLM
           end
         end
 
+        def elevenlabs_api_pricing
+          return {} unless defined?(ElevenLabs::ModelRegistry)
+
+          base = config.elevenlabs_base_cost_per_1k || 0.30
+          ElevenLabs::ModelRegistry.models.each_with_object({}) do |model, hash|
+            multiplier = model.dig("model_rates", "character_cost_multiplier") || 1.0
+            hash[model["model_id"]] = (base * multiplier).round(6)
+          end
+        rescue => e
+          warn "[RubyLLM::Agents] Failed to get ElevenLabs API pricing: #{e.message}"
+          {}
+        end
+
         # ============================================================
         # Tier 2: User configuration
         # ============================================================
@@ -207,7 +230,25 @@ module RubyLLM
         end
 
         # ============================================================
-        # Tier 3: Hardcoded fallbacks
+        # Tier 3: ElevenLabs API (dynamic multiplier × base rate)
+        # ============================================================
+
+        def from_elevenlabs_api(model_id)
+          return nil unless defined?(ElevenLabs::ModelRegistry)
+
+          model = ElevenLabs::ModelRegistry.find(model_id)
+          return nil unless model
+
+          multiplier = model.dig("model_rates", "character_cost_multiplier") || 1.0
+          base = config.elevenlabs_base_cost_per_1k || 0.30
+          (base * multiplier).round(6)
+        rescue => e
+          warn "[RubyLLM::Agents] Failed to get ElevenLabs API pricing: #{e.message}"
+          nil
+        end
+
+        # ============================================================
+        # Tier 4: Hardcoded fallbacks
         # ============================================================
 
         def fallback_price(provider, model_id)

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

@@ -318,6 +318,16 @@ module RubyLLM
         context.output_tokens = 0
         context.total_cost = calculate_cost(raw_result)
 
+        # Store transcription-specific metadata for execution tracking
+        context[:language] = resolved_language if resolved_language
+        context[:detected_language] = raw_result[:language] if raw_result[:language]
+        context[:audio_duration_seconds] = raw_result[:duration] if raw_result[:duration]
+        context[:audio_minutes] = (raw_result[:duration] / 60.0).round(4) if raw_result[:duration]
+        context[:output_format] = self.class.output_format.to_s
+        context[:timestamp_granularity] = self.class.include_timestamps.to_s
+        context[:segment_count] = raw_result[:segments]&.size if raw_result[:segments]
+        context[:word_count] = raw_result[:text]&.split(/\s+/)&.size if raw_result[:text]
+
         # Build final result
         context.output = build_result(
           raw_result,

data/lib/ruby_llm/agents/core/configuration.rb

@@ -452,7 +452,10 @@ module RubyLLM
         :root_directory,
         :root_namespace,
         :tool_result_max_length,
-        :redaction
+        :redaction,
+        :persist_audio_data,
+        :elevenlabs_base_cost_per_1k,
+        :elevenlabs_models_cache_ttl
 
       # Attributes with validation (readers only, custom setters below)
       attr_reader :default_temperature,
@@ -734,6 +737,14 @@ module RubyLLM
 
         # Redaction defaults (disabled by default)
         @redaction = nil
+
+        # Audio data persistence (disabled by default — base64 audio can be large)
+        @persist_audio_data = false
+
+        # ElevenLabs dynamic pricing: base cost per 1K characters (Pro plan overage rate)
+        @elevenlabs_base_cost_per_1k = 0.30
+        # ElevenLabs models cache TTL in seconds (6 hours)
+        @elevenlabs_models_cache_ttl = 21_600
       end
 
       # Returns the configured cache store, falling back to Rails.cache

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "3.2.0"
+    VERSION = "3.4.0"
   end
 end

data/lib/ruby_llm/agents/pipeline/middleware/instrumentation.rb

@@ -280,6 +280,9 @@ module RubyLLM
               detail_data[:response] = serialize_response(context)
             end
 
+            # Persist audio data for Speaker executions
+            maybe_persist_audio_response(context, detail_data)
+
             has_data = detail_data.values.any? { |v| v.present? && v != {} && v != [] }
             return unless has_data
 
@@ -376,6 +379,10 @@ module RubyLLM
             if global_config.persist_responses && context.output.respond_to?(:content)
               detail_data[:response] = serialize_response(context)
             end
+
+            # Persist audio data for Speaker executions
+            maybe_persist_audio_response(context, detail_data)
+
             data[:_detail_data] = detail_data
 
             data
@@ -463,6 +470,48 @@ module RubyLLM
             nil
           end
 
+          # Persists audio response data for Speaker executions
+          #
+          # When persist_audio_data is enabled and the output is a SpeechResult with
+          # audio binary data, stores a base64 data URI in the response column.
+          # Always stores audio_url if present (lightweight, no binary).
+          #
+          # @param context [Context] The execution context
+          # @param detail_data [Hash] The detail data hash to modify
+          def maybe_persist_audio_response(context, detail_data)
+            return unless context.output.is_a?(RubyLLM::Agents::SpeechResult)
+
+            # Always persist audio_url if present (it's just a string, no binary)
+            if context.output.audio_url.present?
+              detail_data[:response] ||= {}
+              detail_data[:response][:audio_url] = context.output.audio_url
+            end
+
+            # Persist full audio data URI only when opted in
+            return unless global_config.respond_to?(:persist_audio_data) && global_config.persist_audio_data
+            return unless context.output.audio.present?
+
+            detail_data[:response] = serialize_audio_response(context.output)
+          rescue => e
+            error("Failed to persist audio response: #{e.message}")
+          end
+
+          # Serializes a SpeechResult into a hash for the response column
+          #
+          # @param result [SpeechResult] The speech result to serialize
+          # @return [Hash] Serialized audio response data
+          def serialize_audio_response(result)
+            {
+              audio_data_uri: result.to_data_uri,
+              audio_url: result.audio_url,
+              format: result.format.to_s,
+              duration: result.duration,
+              file_size: result.file_size,
+              voice_id: result.voice_id,
+              provider: result.provider.to_s
+            }.compact
+          end
+
           # Queues async logging via background job
           #
           # @param data [Hash] Execution data

data/lib/ruby_llm/agents/results/speech_result.rb

@@ -29,17 +29,17 @@ module RubyLLM
       #   @return [String, nil] Binary audio data
       attr_reader :audio
 
-      # @!attribute [r] audio_url
+      # @!attribute [rw] audio_url
       #   @return [String, nil] URL if audio was stored remotely
-      attr_reader :audio_url
+      attr_accessor :audio_url
 
-      # @!attribute [r] audio_key
+      # @!attribute [rw] audio_key
       #   @return [String, nil] Storage key if stored
-      attr_reader :audio_key
+      attr_accessor :audio_key
 
-      # @!attribute [r] audio_path
+      # @!attribute [rw] audio_path
       #   @return [String, nil] Local file path if saved
-      attr_reader :audio_path
+      attr_accessor :audio_path
 
       # @!endgroup
 
@@ -308,29 +308,37 @@ module RubyLLM
         }
       end
 
-      private
+      # Returns MIME type for the audio format
+      #
+      # @return [String] MIME type
+      def content_type
+        mime_type_for_format
+      end
 
       # Returns MIME type for the audio format
       #
       # @return [String] MIME type
       def mime_type_for_format
+        fmt = format.to_s
+
+        # Handle ElevenLabs native format strings (e.g., "mp3_44100_128")
+        return "audio/mpeg" if fmt.start_with?("mp3")
+        return "audio/wav" if fmt.start_with?("wav")
+        return "audio/opus" if fmt.start_with?("opus")
+        return "audio/pcm" if fmt.start_with?("pcm")
+        return "audio/alaw" if fmt.start_with?("alaw")
+        return "audio/basic" if fmt.start_with?("ulaw")
+
+        # Handle simple symbols (backward compatible)
         case format
-        when :mp3
-          "audio/mpeg"
-        when :wav
-          "audio/wav"
-        when :ogg
-          "audio/ogg"
-        when :flac
-          "audio/flac"
-        when :aac
-          "audio/aac"
-        when :opus
-          "audio/opus"
-        when :pcm
-          "audio/pcm"
-        else
-          "audio/mpeg" # Default to mp3
+        when :mp3 then "audio/mpeg"
+        when :wav then "audio/wav"
+        when :ogg then "audio/ogg"
+        when :flac then "audio/flac"
+        when :aac then "audio/aac"
+        when :opus then "audio/opus"
+        when :pcm then "audio/pcm"
+        else "audio/mpeg"
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.4.0
 platform: ruby
 authors:
 - adham90
@@ -111,6 +111,7 @@ files:
 - app/views/ruby_llm/agents/dashboard/_action_center.html.erb
 - app/views/ruby_llm/agents/dashboard/_tenant_budget.html.erb
 - app/views/ruby_llm/agents/dashboard/index.html.erb
+- app/views/ruby_llm/agents/executions/_audio_player.html.erb
 - app/views/ruby_llm/agents/executions/_execution.html.erb
 - app/views/ruby_llm/agents/executions/_filters.html.erb
 - app/views/ruby_llm/agents/executions/_list.html.erb
@@ -208,7 +209,9 @@ files:
 - lib/generators/ruby_llm_agents/upgrade_generator.rb
 - lib/ruby_llm-agents.rb
 - lib/ruby_llm/agents.rb
+- lib/ruby_llm/agents/audio/elevenlabs/model_registry.rb
 - lib/ruby_llm/agents/audio/speaker.rb
+- lib/ruby_llm/agents/audio/speaker/active_storage_support.rb
 - lib/ruby_llm/agents/audio/speech_client.rb
 - lib/ruby_llm/agents/audio/speech_pricing.rb
 - lib/ruby_llm/agents/audio/transcriber.rb