ruby_llm-agents 3.1.0 → 3.3.0

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

@@ -390,79 +390,85 @@ module RubyLLM
         end
       end
 
+      # Attributes with custom setters (validation) — only readers here
+      attr_reader :default_embedding_dimensions, :default_embedding_batch_size
+
       # Attributes without validation (simple accessors)
       attr_accessor :default_model,
-                    :async_logging,
-                    :async_max_concurrency,
-                    :retention_period,
-                    :dashboard_parent_controller,
-                    :basic_auth_username,
-                    :basic_auth_password,
-                    :default_fallback_models,
-                    :default_total_timeout,
-                    :default_streaming,
-                    :default_tools,
-                    :default_thinking,
-                    :on_alert,
-                    :persist_prompts,
-                    :persist_responses,
-                    :multi_tenancy_enabled,
-                    :persist_messages_summary,
-                    :default_retryable_patterns,
-                    :default_embedding_model,
-                    :default_embedding_dimensions,
-                    :default_embedding_batch_size,
-                    :track_embeddings,
-                    :default_transcription_model,
-                    :track_transcriptions,
-                    :default_tts_provider,
-                    :default_tts_model,
-                    :default_tts_voice,
-                    :track_speech,
-                    :track_executions,
-                    :track_audio,
-                    :track_cache_hits,
-                    :default_image_model,
-                    :default_image_size,
-                    :default_image_quality,
-                    :default_image_style,
-                    :max_image_prompt_length,
-                    :track_image_generation,
-                    :image_model_aliases,
-                    :litellm_pricing_url,
-                    :litellm_pricing_cache_ttl,
-                    :default_image_cost,
-                    :image_model_pricing,
-                    :default_variator_model,
-                    :default_editor_model,
-                    :default_transformer_model,
-                    :default_upscaler_model,
-                    :default_variation_strength,
-                    :default_transform_strength,
-                    :default_analyzer_model,
-                    :default_analysis_type,
-                    :default_analyzer_max_tags,
-                    :default_background_remover_model,
-                    :default_background_output_format,
-                    :root_directory,
-                    :root_namespace,
-                    :tool_result_max_length,
-                    :redaction
+        :async_logging,
+        :async_max_concurrency,
+        :retention_period,
+        :dashboard_parent_controller,
+        :basic_auth_username,
+        :basic_auth_password,
+        :default_fallback_models,
+        :default_total_timeout,
+        :default_streaming,
+        :default_tools,
+        :default_thinking,
+        :on_alert,
+        :persist_prompts,
+        :persist_responses,
+        :multi_tenancy_enabled,
+        :persist_messages_summary,
+        :default_retryable_patterns,
+        :default_embedding_model,
+        :track_embeddings,
+        :default_transcription_model,
+        :track_transcriptions,
+        :default_tts_provider,
+        :default_tts_model,
+        :default_tts_voice,
+        :track_speech,
+        :elevenlabs_api_key,
+        :elevenlabs_api_base,
+        :tts_model_pricing,
+        :default_tts_cost,
+        :track_executions,
+        :track_audio,
+        :track_cache_hits,
+        :default_image_model,
+        :default_image_size,
+        :default_image_quality,
+        :default_image_style,
+        :max_image_prompt_length,
+        :track_image_generation,
+        :image_model_aliases,
+        :litellm_pricing_url,
+        :litellm_pricing_cache_ttl,
+        :default_image_cost,
+        :image_model_pricing,
+        :default_variator_model,
+        :default_editor_model,
+        :default_transformer_model,
+        :default_upscaler_model,
+        :default_variation_strength,
+        :default_transform_strength,
+        :default_analyzer_model,
+        :default_analysis_type,
+        :default_analyzer_max_tags,
+        :default_background_remover_model,
+        :default_background_output_format,
+        :root_directory,
+        :root_namespace,
+        :tool_result_max_length,
+        :redaction,
+        :persist_audio_data
 
       # Attributes with validation (readers only, custom setters below)
       attr_reader :default_temperature,
-                  :default_timeout,
-                  :anomaly_cost_threshold,
-                  :anomaly_duration_threshold,
-                  :per_page,
-                  :recent_executions_limit,
-                  :job_retry_attempts,
-                  :messages_summary_max_length,
-                  :dashboard_auth,
-                  :tenant_resolver,
-                  :tenant_config_resolver,
-                  :default_retries,
-                  :budgets
+        :default_timeout,
+        :anomaly_cost_threshold,
+        :anomaly_duration_threshold,
+        :per_page,
+        :recent_executions_limit,
+        :job_retry_attempts,
+        :messages_summary_max_length,
+        :dashboard_auth,
+        :tenant_resolver,
+        :tenant_config_resolver,
+        :default_retries,
+        :budgets
 
       attr_writer :cache_store
 
@@ -597,7 +603,7 @@ module RubyLLM
       # @param value [Integer, nil] Dimensions (must be nil or > 0)
       # @raise [ArgumentError] If value is not nil or positive
       def default_embedding_dimensions=(value)
-        unless value.nil? || (value.is_a?(Numeric) && value > 0)
+        if !value.nil? && !(value.is_a?(Numeric) && value > 0)
           raise ArgumentError, "default_embedding_dimensions must be nil or greater than 0"
         end
 
@@ -627,13 +633,13 @@ module RubyLLM
         @job_retry_attempts = 3
 
         # Reliability defaults (all disabled by default for backward compatibility)
-        @default_retries = { max: 0, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [] }
+        @default_retries = {max: 0, backoff: :exponential, base: 0.4, max_delay: 3.0, on: []}
         @default_fallback_models = []
         @default_total_timeout = nil
         @default_retryable_patterns = {
           rate_limiting: ["rate limit", "rate_limit", "too many requests", "429", "quota"],
           server_errors: ["500", "502", "503", "504", "service unavailable",
-                         "internal server error", "bad gateway", "gateway timeout"],
+            "internal server error", "bad gateway", "gateway timeout"],
           capacity: ["overloaded", "capacity"]
         }
 
@@ -650,7 +656,7 @@ module RubyLLM
 
         # Multi-tenancy defaults (disabled for backward compatibility)
         @multi_tenancy_enabled = false
-        @tenant_resolver = -> { nil }
+        @tenant_resolver = -> {}
         @tenant_config_resolver = nil
 
         # Messages summary defaults
@@ -673,6 +679,14 @@ module RubyLLM
         @default_tts_voice = "nova"
         @track_speech = true
 
+        # ElevenLabs defaults
+        @elevenlabs_api_key = nil
+        @elevenlabs_api_base = "https://api.elevenlabs.io"
+
+        # TTS pricing defaults
+        @tts_model_pricing = {}
+        @default_tts_cost = 0.015
+
         # Execution/conversation agent tracking
         @track_executions = true
         @track_audio = true
@@ -721,6 +735,9 @@ module RubyLLM
 
         # Redaction defaults (disabled by default)
         @redaction = nil
+
+        # Audio data persistence (disabled by default — base64 audio can be large)
+        @persist_audio_data = false
       end
 
       # Returns the configured cache store, falling back to Rails.cache
@@ -783,7 +800,7 @@ module RubyLLM
         return false unless async_available?
 
         defined?(::Async::Task) && ::Async::Task.current?
-      rescue StandardError
+      rescue
         false
       end
 

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

@@ -29,7 +29,7 @@ module RubyLLM
 
       def initialize(message = nil, model: nil)
         @model = model
-        super(message || "Circuit breaker is open#{model ? " for #{model}" : ""}")
+        super(message || "Circuit breaker is open#{" for #{model}" if model}")
       end
     end
 
@@ -78,7 +78,7 @@ module RubyLLM
       def initialize(message = nil, tenant_id: nil, budget_type: nil)
         @tenant_id = tenant_id
         @budget_type = budget_type
-        super(message || "Budget exceeded#{tenant_id ? " for tenant #{tenant_id}" : ""}")
+        super(message || "Budget exceeded#{" for tenant #{tenant_id}" if tenant_id}")
       end
     end
 
@@ -88,5 +88,30 @@ module RubyLLM
 
     # Raised for configuration issues
     class ConfigurationError < Error; end
+
+    # ============================================================
+    # Speech/Audio Errors
+    # ============================================================
+
+    # Raised when a TTS provider is not supported
+    class UnsupportedProviderError < Error
+      attr_reader :provider
+
+      def initialize(message = nil, provider: nil)
+        @provider = provider
+        super(message || "Provider :#{provider} is not supported for this operation")
+      end
+    end
+
+    # Raised when the TTS API returns an error response
+    class SpeechApiError < Error
+      attr_reader :status, :response_body
+
+      def initialize(message = nil, status: nil, response_body: nil)
+        @status = status
+        @response_body = response_body
+        super(message || "Speech API error (status: #{status})")
+      end
+    end
   end
 end

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

@@ -63,48 +63,46 @@ module RubyLLM
         # Use catch to intercept successful early returns from the block
         # The block uses `throw :execution_success, result` instead of `return`
         result = catch(:execution_success) do
+          yield(attempt_tracker)
+          # If we reach here normally (no throw), the block completed without success
+          # This happens when AllModelsExhaustedError is raised
+          nil
+        rescue Timeout::Error, Reliability::TotalTimeoutError => e
+          raised_exception = e
+          begin
+            complete_execution_with_attempts(
+              execution,
+              attempt_tracker: attempt_tracker,
+              completed_at: Time.current,
+              status: "timeout",
+              error: e
+            )
+            @status_update_completed = true
+          rescue => completion_err
+            completion_error = completion_err
+          end
+          raise
+        rescue => e
+          raised_exception = e
           begin
-            yield(attempt_tracker)
-            # If we reach here normally (no throw), the block completed without success
-            # This happens when AllModelsExhaustedError is raised
-            nil
-          rescue Timeout::Error, Reliability::TotalTimeoutError => e
-            raised_exception = e
-            begin
-              complete_execution_with_attempts(
-                execution,
-                attempt_tracker: attempt_tracker,
-                completed_at: Time.current,
-                status: "timeout",
-                error: e
-              )
-              @status_update_completed = true
-            rescue StandardError => completion_err
-              completion_error = completion_err
-            end
-            raise
-          rescue StandardError => e
-            raised_exception = e
-            begin
-              complete_execution_with_attempts(
-                execution,
-                attempt_tracker: attempt_tracker,
-                completed_at: Time.current,
-                status: "error",
-                error: e
-              )
-              @status_update_completed = true
-            rescue StandardError => completion_err
-              completion_error = completion_err
-            end
-            raise
-          ensure
-            # Only run emergency fallback if we haven't completed AND we're not in success path
-            # The success path completion happens AFTER the catch block
-            unless @status_update_completed || !$!
-              actual_error = completion_error || raised_exception || $!
-              mark_execution_failed!(execution, error: actual_error)
-            end
+            complete_execution_with_attempts(
+              execution,
+              attempt_tracker: attempt_tracker,
+              completed_at: Time.current,
+              status: "error",
+              error: e
+            )
+            @status_update_completed = true
+          rescue => completion_err
+            completion_error = completion_err
+          end
+          raise
+        ensure
+          # Only run emergency fallback if we haven't completed AND we're not in success path
+          # The success path completion happens AFTER the catch block
+          unless @status_update_completed || !$!
+            actual_error = completion_error || raised_exception || $!
+            mark_execution_failed!(execution, error: actual_error)
           end
         end
 
@@ -119,7 +117,7 @@ module RubyLLM
               status: "success"
             )
             @status_update_completed = true
-          rescue StandardError => e
+          rescue => e
             Rails.logger.error("[RubyLLM::Agents] Failed to complete successful execution: #{e.class}: #{e.message}")
             mark_execution_failed!(execution, error: e)
           end
@@ -165,7 +163,7 @@ module RubyLLM
               response: @last_response
             )
             @status_update_completed = true
-          rescue StandardError => e
+          rescue => e
             completion_error = e
             # Don't re-raise - let ensure block handle via mark_execution_failed!
           end
@@ -181,11 +179,11 @@ module RubyLLM
               error: e
             )
             @status_update_completed = true
-          rescue StandardError => completion_err
+          rescue => completion_err
             completion_error = completion_err
           end
           raise
-        rescue StandardError => e
+        rescue => e
           raised_exception = e
           begin
             complete_execution(
@@ -195,7 +193,7 @@ module RubyLLM
               error: e
             )
             @status_update_completed = true
-          rescue StandardError => completion_err
+          rescue => completion_err
             completion_error = completion_err
           end
           raise
@@ -258,7 +256,7 @@ module RubyLLM
         # Add fallback chain tracking (count only on execution, chain stored in detail)
         if fallback_chain.any?
           execution_data[:attempts_count] = 0
-          @_pending_detail_data = { fallback_chain: fallback_chain, attempts: [] }
+          @_pending_detail_data = {fallback_chain: fallback_chain, attempts: []}
         end
 
         # Add tenant_id if multi-tenancy is enabled
@@ -285,7 +283,7 @@ module RubyLLM
         execution.create_detail!(detail_data) if has_data
 
         execution
-      rescue StandardError => e
+      rescue => e
         # Log error but don't fail the agent execution itself
         Rails.logger.error("[RubyLLM::Agents] Failed to create execution record: #{e.message}")
         nil
@@ -356,7 +354,7 @@ module RubyLLM
           begin
             execution.calculate_costs!
             execution.save!
-          rescue StandardError => cost_error
+          rescue => cost_error
             Rails.logger.warn("[RubyLLM::Agents] Cost calculation failed: #{cost_error.message}")
           end
         end
@@ -364,12 +362,12 @@ module RubyLLM
         # Record token usage for budget tracking
         record_token_usage(execution)
       rescue ActiveRecord::RecordInvalid => e
-        Rails.logger.error("[RubyLLM::Agents] Validation failed for execution #{execution&.id}: #{e.record.errors.full_messages.join(', ')}")
+        Rails.logger.error("[RubyLLM::Agents] Validation failed for execution #{execution&.id}: #{e.record.errors.full_messages.join(", ")}")
         if Rails.env.development? || Rails.env.test?
           Rails.logger.error("[RubyLLM::Agents] Update data: #{update_data.inspect}")
         end
         raise
-      rescue StandardError => e
+      rescue => e
         Rails.logger.error("[RubyLLM::Agents] Failed to update execution record #{execution&.id}: #{e.class}: #{e.message}")
         if Rails.env.development? || Rails.env.test?
           Rails.logger.error("[RubyLLM::Agents] Update data: #{update_data.inspect}")
@@ -465,7 +463,7 @@ module RubyLLM
           begin
             execution.aggregate_attempt_costs!
             execution.save!
-          rescue StandardError => cost_error
+          rescue => cost_error
             Rails.logger.warn("[RubyLLM::Agents] Cost calculation failed: #{cost_error.message}")
           end
         end
@@ -473,12 +471,12 @@ module RubyLLM
         # Record token usage for budget tracking
         record_token_usage(execution)
       rescue ActiveRecord::RecordInvalid => e
-        Rails.logger.error("[RubyLLM::Agents] Validation failed for execution #{execution&.id}: #{e.record.errors.full_messages.join(', ')}")
+        Rails.logger.error("[RubyLLM::Agents] Validation failed for execution #{execution&.id}: #{e.record.errors.full_messages.join(", ")}")
         if Rails.env.development? || Rails.env.test?
           Rails.logger.error("[RubyLLM::Agents] Update data: #{update_data.inspect}")
         end
         raise
-      rescue StandardError => e
+      rescue => e
         Rails.logger.error("[RubyLLM::Agents] Failed to update execution record #{execution&.id}: #{e.class}: #{e.message}")
         if Rails.env.development? || Rails.env.test?
           Rails.logger.error("[RubyLLM::Agents] Update data: #{update_data.inspect}")
@@ -624,7 +622,7 @@ module RubyLLM
       # @return [String, nil] The system prompt or nil if unavailable
       def safe_system_prompt
         respond_to?(:system_prompt) ? system_prompt.to_s : nil
-      rescue StandardError => e
+      rescue => e
         Rails.logger.warn("[RubyLLM::Agents] Could not capture system_prompt: #{e.message}")
         nil
       end
@@ -634,7 +632,7 @@ module RubyLLM
       # @return [String, nil] The user prompt or nil if unavailable
       def safe_user_prompt
         respond_to?(:user_prompt) ? user_prompt.to_s : nil
-      rescue StandardError => e
+      rescue => e
         Rails.logger.warn("[RubyLLM::Agents] Could not capture user_prompt: #{e.message}")
         nil
       end
@@ -644,7 +642,7 @@ module RubyLLM
       # @return [String, nil] The assistant prompt or nil if unavailable
       def safe_assistant_prompt
         respond_to?(:assistant_prompt) ? assistant_prompt&.to_s : nil
-      rescue StandardError => e
+      rescue => e
         Rails.logger.warn("[RubyLLM::Agents] Could not capture assistant_prompt: #{e.message}")
         nil
       end
@@ -665,7 +663,7 @@ module RubyLLM
       def safe_response_value(response, method, default = nil)
         return default unless response.respond_to?(method)
         response.public_send(method)
-      rescue StandardError
+      rescue
         default
       end
 
@@ -702,7 +700,7 @@ module RubyLLM
       # @return [String, nil] Normalized finish reason
       def safe_extract_finish_reason(response)
         reason = safe_response_value(response, :finish_reason) ||
-                 safe_response_value(response, :stop_reason)
+          safe_response_value(response, :stop_reason)
         return nil unless reason
 
         # Normalize to standard values
@@ -850,7 +848,7 @@ module RubyLLM
           if tool_call.respond_to?(:to_h)
             tool_call.to_h
           else
-            { id: id, name: tool_call[:name], arguments: tool_call[:arguments] }
+            {id: id, name: tool_call[:name], arguments: tool_call[:arguments]}
           end
         end
       end
@@ -919,7 +917,7 @@ module RubyLLM
           }
           execution.create_detail!(detail_data) if detail_data.values.any?(&:present?)
         end
-      rescue StandardError => e
+      rescue => e
         Rails.logger.error("[RubyLLM::Agents] Failed to record cache hit execution: #{e.message}")
       end
 
@@ -940,7 +938,7 @@ module RubyLLM
             tenant_id: tenant_id,
             tenant_config: tenant_config
           )
-        rescue StandardError => e
+        rescue => e
           Rails.logger.warn("[RubyLLM::Agents] Failed to record token usage: #{e.message}")
         end
       end
@@ -956,7 +954,7 @@ module RubyLLM
 
         @_assistant_prompt_column_exists = begin
           RubyLLM::Agents::ExecutionDetail.column_names.include?("assistant_prompt")
-        rescue StandardError
+        rescue
           false
         end
       end
@@ -1001,16 +999,16 @@ module RubyLLM
 
         # Store error_message in detail table (best-effort)
         begin
-          detail_attrs = { error_message: error_message.to_s.truncate(65535) }
+          detail_attrs = {error_message: error_message.to_s.truncate(65535)}
           if execution.detail
             execution.detail.update_columns(detail_attrs)
           else
             RubyLLM::Agents::ExecutionDetail.create!(detail_attrs.merge(execution_id: execution.id))
           end
-        rescue StandardError
+        rescue
           # Non-critical — error_class on execution is sufficient for filtering
         end
-      rescue StandardError => e
+      rescue => e
         Rails.logger.error("[RubyLLM::Agents] CRITICAL: Failed emergency status update for execution #{execution&.id}: #{e.message}")
       end
     end

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

@@ -70,9 +70,9 @@ module RubyLLM
       included do
         # Link to gem's Tenant model via polymorphic association
         has_one :llm_tenant_record,
-                class_name: "RubyLLM::Agents::Tenant",
-                as: :tenant_record,
-                dependent: :destroy
+          class_name: "RubyLLM::Agents::Tenant",
+          as: :tenant_record,
+          dependent: :destroy
 
         # Backward compatible alias (llm_budget points to same Tenant record)
         # @deprecated Use llm_tenant_record instead
@@ -106,10 +106,10 @@ module RubyLLM
 
           # Executions tracked for this tenant via tenant_id string column
           has_many :llm_executions,
-                   class_name: "RubyLLM::Agents::Execution",
-                   foreign_key: :tenant_id,
-                   primary_key: id,
-                   dependent: :nullify
+            class_name: "RubyLLM::Agents::Execution",
+            foreign_key: :tenant_id,
+            primary_key: id,
+            dependent: :nullify
 
           # Auto-create tenant record callback
           after_create :create_default_llm_tenant if llm_tenant_options[:budget]

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.1.0"
+    VERSION = "3.3.0"
   end
 end

data/lib/ruby_llm/agents/dsl/base.rb

@@ -56,7 +56,7 @@ module RubyLLM
       #
       module Base
         # Regex pattern to extract {placeholder} parameters from prompt strings
-        PLACEHOLDER_PATTERN = /\{(\w+)\}/.freeze
+        PLACEHOLDER_PATTERN = /\{(\w+)\}/
 
         # @!group Configuration DSL
 
@@ -306,7 +306,7 @@ module RubyLLM
         # @return [String] The default model
         def default_model
           RubyLLM::Agents.configuration.default_model
-        rescue StandardError
+        rescue
           "gpt-4o"
         end
 
@@ -315,7 +315,7 @@ module RubyLLM
         # @return [Integer] The default timeout
         def default_timeout
           RubyLLM::Agents.configuration.default_timeout
-        rescue StandardError
+        rescue
           120
         end
       end