ruby_llm-agents 1.3.3 → 2.0.0

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

@@ -7,20 +7,39 @@ module RubyLLM
       #
       # Provides common configuration methods that every agent type needs:
       # - model: The LLM model to use
-      # - version: Cache invalidation version
+      # - prompt: The user prompt (string with {placeholders} or block)
+      # - system: System instructions
       # - description: Human-readable description
       # - timeout: Request timeout
+      # - returns: Structured output schema
       #
-      # @example Basic usage
-      #   class MyAgent < RubyLLM::Agents::BaseAgent
-      #     extend DSL::Base
-      #
+      # @example Simplified DSL
+      #   class SearchAgent < RubyLLM::Agents::BaseAgent
       #     model "gpt-4o"
-      #     version "2.0"
-      #     description "A helpful agent"
+      #     system "You are a helpful search assistant."
+      #     prompt "Search for: {query} (limit: {limit})"
+      #
+      #     param :limit, default: 10  # Override auto-detected param
+      #
+      #     returns do
+      #       array :results do
+      #         string :title
+      #         string :url
+      #       end
+      #     end
+      #   end
+      #
+      # @example Dynamic prompt with block
+      #   class SummaryAgent < RubyLLM::Agents::BaseAgent
+      #     prompt do
+      #       "Summarize in #{word_count} words: #{text}"
+      #     end
       #   end
       #
       module Base
+        # Regex pattern to extract {placeholder} parameters from prompt strings
+        PLACEHOLDER_PATTERN = /\{(\w+)\}/.freeze
+
         # @!group Configuration DSL
 
         # Sets or returns the LLM model for this agent class
@@ -34,18 +53,75 @@ module RubyLLM
           @model || inherited_or_default(:model, default_model)
         end
 
-        # Sets or returns the version string for cache invalidation
+        # Sets the user prompt template or block
         #
-        # Change this when you want to invalidate cached results
-        # (e.g., after changing prompts or behavior).
+        # When a string is provided, {placeholder} syntax is used to interpolate
+        # parameters. Parameters are automatically registered (as required) unless
+        # already defined with `param`.
         #
-        # @param value [String, nil] Version string
-        # @return [String] The current version
-        # @example
-        #   version "2.0"
-        def version(value = nil)
-          @version = value if value
-          @version || inherited_or_default(:version, "1.0")
+        # When a block is provided, it's evaluated in the instance context at
+        # execution time, allowing access to all instance methods and parameters.
+        #
+        # @param template [String, nil] Prompt template with {placeholder} syntax
+        # @yield Block that returns the prompt string (evaluated at execution time)
+        # @return [String, Proc, nil] The current prompt configuration
+        #
+        # @example With template string (parameters auto-detected)
+        #   prompt "Search for: {query} in {category}"
+        #   # Automatically registers :query and :category as required params
+        #
+        # @example With block for dynamic prompts
+        #   prompt do
+        #     base = "Analyze the following"
+        #     base += " in #{language}" if language != "en"
+        #     "#{base}: #{text}"
+        #   end
+        #
+        def prompt(template = nil, &block)
+          if template
+            @prompt_template = template
+            auto_register_params_from_template(template)
+          elsif block
+            @prompt_block = block
+          end
+          @prompt_template || @prompt_block || inherited_or_default(:prompt_config, nil)
+        end
+
+        # Returns the prompt configuration (template or block)
+        #
+        # @return [String, Proc, nil] The prompt template, block, or nil
+        def prompt_config
+          @prompt_template || @prompt_block || inherited_or_default(:prompt_config, nil)
+        end
+
+        # Sets the system prompt/instructions
+        #
+        # @param text [String, nil] System instructions for the LLM
+        # @yield Block that returns the system prompt (evaluated at execution time)
+        # @return [String, Proc, nil] The current system prompt
+        #
+        # @example Static system prompt
+        #   system "You are a helpful assistant. Be concise and accurate."
+        #
+        # @example Dynamic system prompt
+        #   system do
+        #     "You are helping #{user_name}. Their preferences: #{preferences}"
+        #   end
+        #
+        def system(text = nil, &block)
+          if text
+            @system_template = text
+          elsif block
+            @system_block = block
+          end
+          @system_template || @system_block || inherited_or_default(:system_config, nil)
+        end
+
+        # Returns the system prompt configuration
+        #
+        # @return [String, Proc, nil] The system template, block, or nil
+        def system_config
+          @system_template || @system_block || inherited_or_default(:system_config, nil)
         end
 
         # Sets or returns the description for this agent class
@@ -72,10 +148,74 @@ module RubyLLM
           @timeout || inherited_or_default(:timeout, default_timeout)
         end
 
+        # Sets or returns the response schema for structured output
+        #
+        # Accepts a hash (JSON Schema), a block (passed to RubyLLM::Schema.create),
+        # or any object that responds to `to_json_schema`.
+        #
+        # @param value [Hash, Object, nil] The schema to set
+        # @param block [Proc, nil] Block passed to RubyLLM::Schema.create
+        # @return [Hash, RubyLLM::Schema, nil] The current schema setting
+        # @example With a block (recommended)
+        #   schema do
+        #     string :name, description: "The user's name"
+        #     integer :age, description: "The user's age"
+        #   end
+        # @example With a hash
+        #   schema type: "object", properties: { name: { type: "string" } }
+        def schema(value = nil, &block)
+          if value
+            @schema = value
+          elsif block
+            @schema = RubyLLM::Schema.create(&block)
+          end
+          @schema || inherited_or_default(:schema, nil)
+        end
+
+        # Alias for schema with a clearer name
+        #
+        # Defines the structured output schema for this agent.
+        # This is the preferred method for defining schemas in the simplified DSL.
+        #
+        # @param block [Proc] Block passed to RubyLLM::Schema.create
+        # @return [RubyLLM::Schema, nil] The current schema setting
+        #
+        # @example
+        #   returns do
+        #     string :summary, "A brief summary"
+        #     array :insights, of: :string, description: "Key insights"
+        #     number :confidence, "Confidence score from 0 to 1"
+        #   end
+        #
+        def returns(&block)
+          schema(&block)
+        end
+
         # @!endgroup
 
         private
 
+        # Auto-registers parameters found in prompt template placeholders
+        #
+        # Extracts {placeholder} patterns from the template and registers
+        # each as a required parameter (unless already defined).
+        #
+        # @param template [String] The prompt template
+        # @return [void]
+        def auto_register_params_from_template(template)
+          return unless respond_to?(:param)
+
+          placeholders = template.scan(PLACEHOLDER_PATTERN).flatten.map(&:to_sym)
+          existing_params = respond_to?(:params) ? params.keys : []
+
+          placeholders.each do |placeholder|
+            next if existing_params.include?(placeholder)
+
+            # Auto-register as required parameter
+            param(placeholder, required: true)
+          end
+        end
+
         # Looks up setting from superclass or uses default
         #
         # @param method [Symbol] The method to call on superclass

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

@@ -43,8 +43,39 @@ module RubyLLM
           @cache_ttl = ttl
         end
 
-        # Alias for cache_for (for backward compatibility)
-        alias cache cache_for
+        # Unified cache configuration method (simplified DSL)
+        #
+        # Configures caching with a cleaner syntax using keyword arguments.
+        #
+        # @param ttl_or_options [ActiveSupport::Duration, Hash] TTL or options hash
+        # @param for_duration [ActiveSupport::Duration] TTL for cached responses
+        # @param key [Array<Symbol>] Parameters to include in cache key
+        # @return [void]
+        #
+        # @example Simple TTL (positional argument for backward compatibility)
+        #   cache 1.hour
+        #
+        # @example With keyword arguments (preferred)
+        #   cache for: 1.hour
+        #   cache for: 30.minutes, key: [:query, :user_id]
+        #
+        def cache(ttl_or_options = nil, for: nil, key: nil)
+          # Handle positional argument (backward compatibility)
+          if ttl_or_options && !ttl_or_options.is_a?(Hash)
+            @cache_enabled = true
+            @cache_ttl = ttl_or_options
+            return
+          end
+
+          # Handle keyword arguments
+          for_duration = binding.local_variable_get(:for)
+          if for_duration
+            @cache_enabled = true
+            @cache_ttl = for_duration
+          end
+
+          @cache_key_includes = Array(key) if key
+        end
 
         # Returns whether caching is enabled for this agent
         #

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

@@ -57,6 +57,35 @@ module RubyLLM
           @non_fallback_errors = builder.non_fallback_errors_list if builder.non_fallback_errors_list
         end
 
+        # Alias for reliability with clearer intent-revealing name
+        #
+        # Configures what happens when an LLM call fails.
+        # This is the preferred method in the simplified DSL.
+        #
+        # @yield Block containing failure handling configuration
+        # @return [void]
+        #
+        # @example
+        #   on_failure do
+        #     retry times: 3, backoff: :exponential
+        #     fallback to: ["gpt-4o-mini", "gpt-3.5-turbo"]
+        #     circuit_breaker after: 5, cooldown: 5.minutes
+        #     timeout 30.seconds
+        #   end
+        #
+        def on_failure(&block)
+          builder = OnFailureBuilder.new
+          builder.instance_eval(&block)
+
+          @retries_config = builder.retries_config if builder.retries_config
+          @fallback_models = builder.fallback_models_list if builder.fallback_models_list.any?
+          @fallback_providers = builder.fallback_providers_list if builder.fallback_providers_list.any?
+          @total_timeout = builder.total_timeout_value if builder.total_timeout_value
+          @circuit_breaker_config = builder.circuit_breaker_config if builder.circuit_breaker_config
+          @retryable_patterns = builder.retryable_patterns_list if builder.retryable_patterns_list
+          @non_fallback_errors = builder.non_fallback_errors_list if builder.non_fallback_errors_list
+        end
+
         # Returns the complete reliability configuration hash
         #
         # Used by the Reliability middleware to get all settings.
@@ -326,6 +355,125 @@ module RubyLLM
             @non_fallback_errors_list = error_classes.flatten
           end
         end
+
+        # Builder class for on_failure block with simplified syntax
+        #
+        # Uses more intuitive method names:
+        # - `retry times:` instead of `retries max:`
+        # - `fallback to:` instead of `fallback_models`
+        # - `circuit_breaker after:` instead of `circuit_breaker errors:`
+        # - `timeout` instead of `total_timeout`
+        #
+        class OnFailureBuilder
+          attr_reader :retries_config, :fallback_models_list, :total_timeout_value,
+                      :circuit_breaker_config, :retryable_patterns_list, :fallback_providers_list,
+                      :non_fallback_errors_list
+
+          def initialize
+            @retries_config = nil
+            @fallback_models_list = []
+            @total_timeout_value = nil
+            @circuit_breaker_config = nil
+            @retryable_patterns_list = nil
+            @fallback_providers_list = []
+            @non_fallback_errors_list = nil
+          end
+
+          # Configure retry behavior
+          #
+          # @param times [Integer] Number of retry attempts
+          # @param backoff [Symbol] Backoff strategy (:constant or :exponential)
+          # @param base [Float] Base delay in seconds
+          # @param max_delay [Float] Maximum delay between retries
+          # @param on [Array<Class>] Error classes to retry on
+          #
+          # @example
+          #   retries times: 3, backoff: :exponential
+          #
+          def retries(times: 0, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [])
+            @retries_config = {
+              max: times,
+              backoff: backoff,
+              base: base,
+              max_delay: max_delay,
+              on: on
+            }
+          end
+
+          # Configure fallback models
+          #
+          # @param to [String, Array<String>] Model(s) to fall back to
+          #
+          # @example
+          #   fallback to: "gpt-4o-mini"
+          #   fallback to: ["gpt-4o-mini", "gpt-3.5-turbo"]
+          #
+          def fallback(to:)
+            @fallback_models_list = Array(to)
+          end
+
+          # Also support fallback_models for compatibility
+          def fallback_models(*models)
+            @fallback_models_list = models.flatten
+          end
+
+          # Configure a fallback provider (for audio agents)
+          #
+          # @param provider [Symbol] The provider to fall back to
+          # @param options [Hash] Provider-specific options
+          #
+          def fallback_provider(provider, **options)
+            @fallback_providers_list << { provider: provider, **options }
+          end
+
+          # Configure timeout for all retry/fallback attempts
+          #
+          # @param duration [Integer, ActiveSupport::Duration] Timeout duration
+          #
+          # @example
+          #   timeout 30
+          #   timeout 30.seconds
+          #
+          def timeout(duration)
+            # Handle ActiveSupport::Duration
+            @total_timeout_value = duration.respond_to?(:to_i) ? duration.to_i : duration
+          end
+
+          # Also support total_timeout for compatibility
+          alias total_timeout timeout
+
+          # Configure circuit breaker
+          #
+          # @param after [Integer] Number of errors to trigger open state
+          # @param errors [Integer] Alias for after (compatibility)
+          # @param within [Integer] Rolling window in seconds
+          # @param cooldown [Integer, ActiveSupport::Duration] Cooldown period
+          #
+          # @example
+          #   circuit_breaker after: 5, cooldown: 5.minutes
+          #   circuit_breaker errors: 10, within: 60, cooldown: 300
+          #
+          def circuit_breaker(after: nil, errors: nil, within: 60, cooldown: 300)
+            error_threshold = after || errors || 10
+            cooldown_seconds = cooldown.respond_to?(:to_i) ? cooldown.to_i : cooldown
+
+            @circuit_breaker_config = {
+              errors: error_threshold,
+              within: within,
+              cooldown: cooldown_seconds
+            }
+          end
+
+          # Configure additional retryable patterns
+          def retryable_patterns(*patterns)
+            @retryable_patterns_list = patterns.flatten
+          end
+
+          # Configure errors that should never trigger fallback
+          def non_fallback_errors(*error_classes)
+            @non_fallback_errors_list = error_classes.flatten
+          end
+        end
       end
     end
   end

data/lib/ruby_llm/agents/dsl.rb

@@ -11,7 +11,7 @@ module RubyLLM
     # The DSL modules provide a clean, declarative way to configure agents
     # at the class level. Each module focuses on a specific concern:
     #
-    # - {DSL::Base} - Core settings (model, version, description, timeout)
+    # - {DSL::Base} - Core settings (model, description, timeout)
     # - {DSL::Reliability} - Retries, fallbacks, circuit breakers
     # - {DSL::Caching} - Response caching configuration
     #
@@ -22,7 +22,6 @@ module RubyLLM
     #     extend DSL::Caching
     #
     #     model "gpt-4o"
-    #     version "2.0"
     #     description "A helpful agent"
     #     timeout 30
     #

data/lib/ruby_llm/agents/image/analyzer/execution.rb

@@ -365,7 +365,6 @@ module RubyLLM
           [
             "image_analyzer",
             self.class.name,
-            self.class.version,
             resolve_model,
             resolve_analysis_type.to_s,
             resolve_extract_colors.to_s,
@@ -387,7 +386,7 @@ module RubyLLM
           end
         end
 
-        def build_execution_metadata(result)
+        def build_metadata(result)
           {
             analysis_type: result.analysis_type,
             tags_count: result.tags.size,

data/lib/ruby_llm/agents/image/background_remover/execution.rb

@@ -203,7 +203,6 @@ module RubyLLM
           [
             "background_remover",
             self.class.name,
-            self.class.version,
             resolve_model,
             resolve_output_format.to_s,
             resolve_alpha_matting.to_s,
@@ -226,7 +225,7 @@ module RubyLLM
           end
         end
 
-        def build_execution_metadata(result)
+        def build_metadata(result)
           {
             output_format: result.output_format,
             alpha_matting: result.alpha_matting,

data/lib/ruby_llm/agents/image/concerns/image_operation_dsl.rb

@@ -5,7 +5,7 @@ module RubyLLM
     module Concerns
       # Shared DSL methods for all image operation classes
       #
-      # Provides common configuration options like model, version,
+      # Provides common configuration options like model,
       # description, and caching that are shared across ImageVariator,
       # ImageEditor, ImageTransformer, and ImageUpscaler.
       #
@@ -22,18 +22,6 @@ module RubyLLM
           end
         end
 
-        # Set or get the version
-        #
-        # @param value [String, nil] Version identifier
-        # @return [String] The version
-        def version(value = nil)
-          if value
-            @version = value
-          else
-            @version || inherited_or_default(:version, "v1")
-          end
-        end
-
         # Set or get the description
         #
         # @param value [String, nil] Description

data/lib/ruby_llm/agents/image/concerns/image_operation_execution.rb

@@ -118,7 +118,7 @@ module RubyLLM
             duration_ms: result.duration_ms,
             started_at: result.started_at,
             completed_at: result.completed_at,
-            metadata: build_execution_metadata(result)
+            metadata: build_metadata(result)
           }
         end
 
@@ -141,7 +141,7 @@ module RubyLLM
           }
         end
 
-        def build_execution_metadata(result)
+        def build_metadata(result)
           { count: result.count }
         end
 

data/lib/ruby_llm/agents/image/editor/dsl.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "../concerns/image_operation_dsl"
-require_relative "../generator/content_policy"
 
 module RubyLLM
   module Agents
@@ -15,7 +14,6 @@ module RubyLLM
       #   class ProductEditor < RubyLLM::Agents::ImageEditor
       #     model "gpt-image-1"
       #     size "1024x1024"
-      #     content_policy :strict
       #   end
       #
       module DSL
@@ -33,18 +31,6 @@ module RubyLLM
           end
         end
 
-        # Set or get the content policy level
-        #
-        # @param level [Symbol, nil] Policy level (:none, :standard, :moderate, :strict)
-        # @return [Symbol] The content policy level
-        def content_policy(level = nil)
-          if level
-            @content_policy = level
-          else
-            @content_policy || inherited_or_default(:content_policy, :standard)
-          end
-        end
-
         private
 
         def default_model

data/lib/ruby_llm/agents/image/editor/execution.rb

@@ -23,7 +23,6 @@ module RubyLLM
           resolve_tenant_context!
           check_budget! if budget_tracking_enabled?
           validate_inputs!
-          validate_content_policy!
 
           # Check cache
           cached = check_cache(ImageEditResult) if cache_enabled?
@@ -81,13 +80,6 @@ module RubyLLM
           end
         end
 
-        def validate_content_policy!
-          policy = self.class.content_policy
-          return if policy == :none || policy == :standard
-
-          ImageGenerator::ContentPolicy.validate!(prompt, policy)
-        end
-
         def edit_images
           count = resolve_count
 
@@ -173,7 +165,6 @@ module RubyLLM
           [
             "image_editor",
             self.class.name,
-            self.class.version,
             resolve_model,
             resolve_size,
             Digest::SHA256.hexdigest(prompt),
@@ -194,7 +185,7 @@ module RubyLLM
           end
         end
 
-        def build_execution_metadata(result)
+        def build_metadata(result)
           {
             count: result.count,
             size: result.size,

data/lib/ruby_llm/agents/image/editor.rb

@@ -57,7 +57,6 @@ module RubyLLM
           subclass.instance_variable_set(:@version, @version)
           subclass.instance_variable_set(:@description, @description)
           subclass.instance_variable_set(:@cache_ttl, @cache_ttl)
-          subclass.instance_variable_set(:@content_policy, @content_policy)
         end
       end
 

data/lib/ruby_llm/agents/image/generator.rb

@@ -80,15 +80,6 @@ module RubyLLM
           @style || inherited_or_default(:style, default_image_style)
         end
 
-        # Sets or returns the content policy level
-        #
-        # @param level [Symbol, nil] Policy level (:none, :standard, :moderate, :strict)
-        # @return [Symbol] The content policy level
-        def content_policy(level = nil)
-          @content_policy = level if level
-          @content_policy || inherited_or_default(:content_policy, :standard)
-        end
-
         # Sets or returns negative prompt (things to avoid in generation)
         #
         # @param value [String, nil] Negative prompt text
@@ -162,7 +153,6 @@ module RubyLLM
           subclass.instance_variable_set(:@version, @version)
           subclass.instance_variable_set(:@description, @description)
           subclass.instance_variable_set(:@cache_ttl, @cache_ttl)
-          subclass.instance_variable_set(:@content_policy, @content_policy)
           subclass.instance_variable_set(:@negative_prompt, @negative_prompt)
           subclass.instance_variable_set(:@seed, @seed)
           subclass.instance_variable_set(:@guidance_scale, @guidance_scale)
@@ -246,7 +236,6 @@ module RubyLLM
         execution_started_at = Time.current
 
         validate_prompt!
-        validate_content_policy!
 
         # Generate image(s)
         images = generate_images
@@ -286,7 +275,6 @@ module RubyLLM
           "ruby_llm_agents",
           "image_generator",
           self.class.name,
-          self.class.version,
           resolved_model,
           resolved_size,
           resolved_quality,
@@ -323,14 +311,6 @@ module RubyLLM
         end
       end
 
-      # Validates prompt against content policy
-      def validate_content_policy!
-        policy = self.class.content_policy
-        return if policy == :none || policy == :standard
-
-        ContentPolicy.validate!(prompt, policy)
-      end
-
       # Generate images using RubyLLM.paint
       def generate_images
         count = @runtime_count
@@ -450,6 +430,5 @@ end
 
 # Load supporting modules after class is defined (they reopen the class)
 require_relative "generator/pricing"
-require_relative "generator/content_policy"
 require_relative "generator/templates"
 require_relative "generator/active_storage_support"

data/lib/ruby_llm/agents/image/pipeline/dsl.rb

@@ -14,7 +14,6 @@ module RubyLLM
       #     step :upscale, upscaler: PhotoUpscaler, scale: 4
       #     step :analyze, analyzer: ProductAnalyzer
       #
-      #     version "1.0"
       #     description "Complete product image pipeline"
       #     stop_on_error true
       #   end
@@ -103,18 +102,6 @@ module RubyLLM
           @callbacks ||= { before: [], after: [] }
         end
 
-        # Set or get the version
-        #
-        # @param value [String, nil] Version identifier
-        # @return [String] The version
-        def version(value = nil)
-          if value
-            @version = value
-          else
-            @version || inherited_or_default(:version, "v1")
-          end
-        end
-
         # Set or get the description
         #
         # @param value [String, nil] Description