Class: RubyLLM::Agents::ImageGenerator

Inherits:
BaseAgent
  • Object
show all
Defined in:
lib/ruby_llm/agents/image/generator.rb,
lib/ruby_llm/agents/image/generator/pricing.rb,
lib/ruby_llm/agents/image/generator/templates.rb,
lib/ruby_llm/agents/image/generator/active_storage_support.rb

Overview

Image generator base class for text-to-image generation using the middleware pipeline

Follows the same patterns as other agents - inherits from BaseAgent for unified execution flow, caching, instrumentation, and budget controls through middleware.

Examples:

Basic usage

result = RubyLLM::Agents::ImageGenerator.call(prompt: "A sunset over mountains")
result.url # => "https://..."

Custom generator class

class LogoGenerator < RubyLLM::Agents::ImageGenerator
  model "gpt-image-1"
  size "1024x1024"
  quality "hd"
  style "vivid"

  description "Generates company logos"
  content_policy :strict
end

result = LogoGenerator.call(prompt: "Minimalist tech company logo")

Defined Under Namespace

Modules: ActiveStorageSupport, Pricing, Templates

Constant Summary

Constants included from DSL::Base

DSL::Base::PLACEHOLDER_PATTERN

Constants included from DSL::Caching

DSL::Caching::DEFAULT_CACHE_TTL

Constants included from CacheHelper

CacheHelper::NAMESPACE

Instance Attribute Summary collapse

Attributes inherited from BaseAgent

#client, #model, #temperature, #tracked_tool_calls

Image-specific DSL collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from BaseAgent

agent_middleware, aliases, all_agent_names, ask, #assistant_prompt, #cache_key_data, #cache_key_hash, config_summary, #messages, param, params, #process_response, #resolved_thinking, #schema, stream, streaming, #system_prompt, temperature, thinking, thinking_config, tools, use_middleware

Methods included from DSL::Base

#active_overrides, #assistant, #assistant_config, #cache_prompts, #clear_override_cache!, #description, #model, #overridable?, #overridable_fields, #returns, #schema, #system, #system_config, #timeout, #user, #user_config

Methods included from DSL::Reliability

#circuit_breaker, #circuit_breaker_config, #fallback_models, #fallback_provider, #fallback_providers, #non_fallback_errors, #on_failure, #reliability, #reliability_config, #reliability_configured?, #retries, #retries_config, #retryable_patterns, #total_timeout

Methods included from DSL::Caching

#cache, #cache_enabled?, #cache_for, #cache_key_excludes, #cache_key_includes, #cache_ttl, #caching_config

Methods included from DSL::Queryable

#cost_by_model, #executions, #failures, #last_run, #stats, #total_spent, #with_params

Methods included from DSL::Knowledge

#knowledge_entries, #knowledge_path, #knows

Methods included from CacheHelper

#cache_delete, #cache_exist?, #cache_increment, #cache_key, #cache_read, #cache_store, #cache_write

Methods included from DSL::Knowledge::InstanceMethods

#compiled_knowledge

Constructor Details

#initialize(prompt:, **options) ⇒ ImageGenerator

Creates a new ImageGenerator instance

Parameters:

  • prompt (String) —

    The text prompt for image generation

  • options (Hash) —

    Additional options



202
203
204
205
206
207
208
209
210
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 202

def initialize(prompt:, **options)
  @prompt = prompt
  @runtime_count = options.delete(:count) || 1

  # Set model to image model if not specified
  options[:model] ||= self.class.model

  super(**options)
end

Instance Attribute Details

#prompt ⇒ Object (readonly) 



196
197
198
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 196

def prompt
  @prompt
end

Class Method Details

.agent_type ⇒ Symbol

Returns the agent type for image generators

Returns:

  • (Symbol) —

    :image



35
36
37
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 35

def agent_type
  :image
end

.call(prompt:, **options) ⇒ ImageGenerationResult

Factory method to execute image generation

Parameters:

  • prompt (String) —

    The text prompt for image generation

  • options (Hash) —

    Additional options

Returns:



142
143
144
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 142

def call(prompt:, **options)
  new(prompt: prompt, **options).call
end

.guidance_scale(value = nil) ⇒ Float?

Sets or returns guidance scale (CFG scale)

Parameters:

  • value (Float, nil) (defaults to: nil) —

    Guidance scale (typically 1.0-20.0)

Returns:

  • (Float, nil) —

    The guidance scale



105
106
107
108
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 105

def guidance_scale(value = nil)
  @guidance_scale = value if value
  @guidance_scale || inherited_or_default(:guidance_scale, nil)
end

.inherited(subclass) ⇒ Object

Ensure subclasses inherit DSL settings



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 147

def inherited(subclass)
  super
  subclass.instance_variable_set(:@model, @model)
  subclass.instance_variable_set(:@size, @size)
  subclass.instance_variable_set(:@quality, @quality)
  subclass.instance_variable_set(:@style, @style)
  subclass.instance_variable_set(:@version, @version)
  subclass.instance_variable_set(:@description, @description)
  subclass.instance_variable_set(:@cache_ttl, @cache_ttl)
  subclass.instance_variable_set(:@negative_prompt, @negative_prompt)
  subclass.instance_variable_set(:@seed, @seed)
  subclass.instance_variable_set(:@guidance_scale, @guidance_scale)
  subclass.instance_variable_set(:@steps, @steps)
  subclass.instance_variable_set(:@template_string, @template_string)
end

.model(value = nil) ⇒ String

Sets or returns the image generation model

Parameters:

  • value (String, nil) (defaults to: nil) —

    Model identifier

Returns:

  • (String) —

    The model to use



45
46
47
48
49
50
51
52
53
54
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 45

def model(value = nil)
  @model = value if value
  return @model if defined?(@model) && @model

  if superclass.respond_to?(:agent_type) && superclass.agent_type == :image
    superclass.model
  else
    default_image_model
  end
end

.negative_prompt(value = nil) ⇒ String?

Sets or returns negative prompt (things to avoid in generation)

Parameters:

  • value (String, nil) (defaults to: nil) —

    Negative prompt text

Returns:

  • (String, nil) —

    The negative prompt



87
88
89
90
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 87

def negative_prompt(value = nil)
  @negative_prompt = value if value
  @negative_prompt || inherited_or_default(:negative_prompt, nil)
end

.quality(value = nil) ⇒ String

Sets or returns the quality level

Parameters:

  • value (String, nil) (defaults to: nil) —

    Quality (“standard”, “hd”)

Returns:

  • (String) —

    The quality to use



69
70
71
72
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 69

def quality(value = nil)
  @quality = value if value
  @quality || inherited_or_default(:quality, default_image_quality)
end

.seed(value = nil) ⇒ Integer?

Sets or returns the seed for reproducible generation

Parameters:

  • value (Integer, nil) (defaults to: nil) —

    Seed value

Returns:

  • (Integer, nil) —

    The seed



96
97
98
99
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 96

def seed(value = nil)
  @seed = value if value
  @seed || inherited_or_default(:seed, nil)
end

.size(value = nil) ⇒ String

Sets or returns the image size

Parameters:

  • value (String, nil) (defaults to: nil) —

    Size (e.g., “1024x1024”, “1792x1024”)

Returns:

  • (String) —

    The size to use



60
61
62
63
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 60

def size(value = nil)
  @size = value if value
  @size || inherited_or_default(:size, default_image_size)
end

.steps(value = nil) ⇒ Integer?

Sets or returns number of inference steps

Parameters:

  • value (Integer, nil) (defaults to: nil) —

    Number of steps

Returns:

  • (Integer, nil) —

    The steps



114
115
116
117
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 114

def steps(value = nil)
  @steps = value if value
  @steps || inherited_or_default(:steps, nil)
end

.style(value = nil) ⇒ String

Sets or returns the style preset

Parameters:

  • value (String, nil) (defaults to: nil) —

    Style (“vivid”, “natural”)

Returns:

  • (String) —

    The style to use



78
79
80
81
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 78

def style(value = nil)
  @style = value if value
  @style || inherited_or_default(:style, default_image_style)
end

.template(value = nil) ⇒ String?

Sets a prompt template (use #prompt as placeholder)

Parameters:

  • value (String, nil) (defaults to: nil) —

    Template string

Returns:

  • (String, nil) —

    The template



123
124
125
126
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 123

def template(value = nil)
  @template_string = value if value
  @template_string || inherited_or_default(:template_string, nil)
end

.template_string ⇒ String?

Gets the template string

Returns:

  • (String, nil) —

    The template string



131
132
133
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 131

def template_string
  @template_string || inherited_or_default(:template_string, nil)
end

Instance Method Details

#agent_cache_key ⇒ String

Generates the cache key for this image generation

Returns:

  • (String) —

    Cache key



274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 274

def agent_cache_key
  components = [
    "ruby_llm_agents",
    "image_generator",
    self.class.name,
    resolved_model,
    resolved_size,
    resolved_quality,
    resolved_style,
    Digest::SHA256.hexdigest(prompt)
  ].compact

  components.join("/")
end

#call ⇒ ImageGenerationResult

Executes the image generation through the middleware pipeline

Returns:



215
216
217
218
219
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 215

def call
  context = build_context
  result_context = Pipeline::Executor.execute(context)
  result_context.output
end

#execute(context) ⇒ void

This method returns an undefined value.

Core image generation execution

This is called by the Pipeline::Executor after middleware has been applied. Only contains the image generation API logic.

Parameters:



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 235

def execute(context)
  execution_started_at = Time.current

  validate_prompt!

  # Generate image(s)
  images = generate_images

  execution_completed_at = Time.current
  ((execution_completed_at - execution_started_at) * 1000).to_i

  # Build result
  result = build_result(
    images: images,
    started_at: context.started_at || execution_started_at,
    completed_at: execution_completed_at,
    tenant_id: context.tenant_id,
    execution_id: context.execution_id
  )

  # Update context with cost info
  context.input_tokens = result.input_tokens
  context.output_tokens = 0
  context.total_cost = result.total_cost

  context.output = result
rescue => e
  execution_completed_at = Time.current
  context.output = build_error_result(
    e,
    started_at: context.started_at || execution_started_at,
    completed_at: execution_completed_at,
    tenant_id: context.tenant_id
  )
end

#user_prompt ⇒ String

The input for this generation operation

Returns:

  • (String) —

    The prompt



224
225
226
 
# File 'lib/ruby_llm/agents/image/generator.rb', line 224

def user_prompt
  prompt
end