ruby_llm-agents 0.5.0 → 1.0.0.beta.1

data/lib/generators/ruby_llm_agents/templates/application_agent.rb.tt

@@ -6,7 +6,7 @@
 # that apply to all agents, or override them per-agent as needed.
 #
 # Example:
-#   class MyAgent < ApplicationAgent
+#   class <%= @root_namespace %>::MyAgent < ApplicationAgent
 #     param :query, required: true
 #
 #     def user_prompt
@@ -15,55 +15,57 @@
 #   end
 #
 # Usage:
-#   MyAgent.call(query: "hello")
-#   MyAgent.call(query: "hello", dry_run: true)    # Debug mode
-#   MyAgent.call(query: "hello", skip_cache: true) # Bypass cache
+#   <%= @root_namespace %>::MyAgent.call(query: "hello")
+#   <%= @root_namespace %>::MyAgent.call(query: "hello", dry_run: true)    # Debug mode
+#   <%= @root_namespace %>::MyAgent.call(query: "hello", skip_cache: true) # Bypass cache
 #
-class ApplicationAgent < RubyLLM::Agents::Base
-  # ============================================
-  # Shared Model Configuration
-  # ============================================
-  # These settings are inherited by all agents
+module <%= @root_namespace %>
+  class ApplicationAgent < RubyLLM::Agents::Base
+    # ============================================
+    # Shared Model Configuration
+    # ============================================
+    # These settings are inherited by all agents
 
-  # model "gemini-2.0-flash"   # Default model for all agents
-  # temperature 0.0            # Default temperature (0.0 = deterministic)
-  # timeout 60                 # Default timeout in seconds
+    # model "gemini-2.0-flash"   # Default model for all agents
+    # temperature 0.0            # Default temperature (0.0 = deterministic)
+    # timeout 60                 # Default timeout in seconds
 
-  # ============================================
-  # Shared Caching
-  # ============================================
+    # ============================================
+    # Shared Caching
+    # ============================================
 
-  # cache 1.hour  # Enable caching for all agents (override per-agent if needed)
+    # cache 1.hour  # Enable caching for all agents (override per-agent if needed)
 
-  # ============================================
-  # Shared Reliability Settings
-  # ============================================
-  # Configure once here, all agents inherit these settings
+    # ============================================
+    # Shared Reliability Settings
+    # ============================================
+    # Configure once here, all agents inherit these settings
 
-  # Automatic retries for all agents
-  # retries max: 2, backoff: :exponential, base: 0.4, max_delay: 3.0
+    # Automatic retries for all agents
+    # retries max: 2, backoff: :exponential, base: 0.4, max_delay: 3.0
 
-  # Shared fallback models
-  # fallback_models ["gpt-4o-mini", "claude-3-haiku"]
+    # Shared fallback models
+    # fallback_models ["gpt-4o-mini", "claude-3-haiku"]
 
-  # Total timeout across retries/fallbacks
-  # total_timeout 30
+    # Total timeout across retries/fallbacks
+    # total_timeout 30
 
-  # Circuit breaker (per agent-model pair)
-  # circuit_breaker errors: 5, within: 60, cooldown: 300
+    # Circuit breaker (per agent-model pair)
+    # circuit_breaker errors: 5, within: 60, cooldown: 300
 
-  # ============================================
-  # Shared Helper Methods
-  # ============================================
-  # Define methods here that can be used by all agents
+    # ============================================
+    # Shared Helper Methods
+    # ============================================
+    # Define methods here that can be used by all agents
 
-  # Example: Common system prompt prefix
-  # def system_prompt_prefix
-  #   "You are an AI assistant for #{Rails.application.class.module_parent_name}."
-  # end
+    # Example: Common system prompt prefix
+    # def system_prompt_prefix
+    #   "You are an AI assistant for #{Rails.application.class.module_parent_name}."
+    # end
 
-  # Example: Common metadata
-  # def execution_metadata
-  #   { app_version: Rails.application.config.version }
-  # end
+    # Example: Common metadata
+    # def execution_metadata
+    #   { app_version: Rails.application.config.version }
+    # end
+  end
 end

data/lib/generators/ruby_llm_agents/templates/application_background_remover.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Image
+    # Base class for all background removers in the application
+    #
+    # Inherits from RubyLLM::Agents::BackgroundRemover and provides a common
+    # foundation for custom background removal classes.
+    #
+    # @example Creating a custom remover
+    #   class ProductBackgroundRemover < ApplicationBackgroundRemover
+    #     model "rembg"
+    #     output_format :png
+    #     refine_edges true
+    #     alpha_matting true
+    #   end
+    #
+    class ApplicationBackgroundRemover < RubyLLM::Agents::BackgroundRemover
+      # Default configuration (can be overridden in subclasses)
+      # model "rembg"
+      # output_format :png
+      # refine_edges false
+      # alpha_matting false
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/templates/application_embedder.rb.tt

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# ApplicationEmbedder - Base class for all embedders in this application
+#
+# All embedders inherit from this class. Configure shared settings here
+# that apply to all embedders, or override them per-embedder as needed.
+#
+# Example:
+#   class <%= @text_namespace %>::DocumentEmbedder < ApplicationEmbedder
+#     dimensions 512  # Reduce dimensions for storage efficiency
+#
+#     def preprocess(text)
+#       text.strip.downcase
+#     end
+#   end
+#
+# Usage:
+#   <%= @text_namespace %>::DocumentEmbedder.call(text: "hello world")
+#   <%= @text_namespace %>::DocumentEmbedder.call(texts: ["hello", "world"])  # Batch
+#
+module <%= @root_namespace %>
+  module Text
+    class ApplicationEmbedder < RubyLLM::Agents::Embedder
+      # ============================================
+      # Shared Model Configuration
+      # ============================================
+      # These settings are inherited by all embedders
+
+      # model "text-embedding-3-small"  # Default embedding model
+      # dimensions 1536                  # Vector dimensions (nil = model default)
+      # batch_size 100                   # Texts per API call for batch processing
+
+      # ============================================
+      # Shared Caching
+      # ============================================
+      # Same text always produces same embedding, so caching is very effective
+
+      # cache_for 1.week  # Cache embeddings for a week
+
+      # ============================================
+      # Shared Preprocessing
+      # ============================================
+      # Override in subclass for custom preprocessing
+
+      # def preprocess(text)
+      #   text.strip.gsub(/\s+/, ' ').truncate(8000)
+      # end
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/templates/application_image_analyzer.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Image
+    # Base class for all image analyzers in the application
+    #
+    # Inherits from RubyLLM::Agents::ImageAnalyzer and provides a common
+    # foundation for custom image analysis classes.
+    #
+    # @example Creating a custom analyzer
+    #   class ProductAnalyzer < ApplicationImageAnalyzer
+    #     model "gpt-4o"
+    #     analysis_type :detailed
+    #     extract_colors true
+    #     detect_objects true
+    #   end
+    #
+    class ApplicationImageAnalyzer < RubyLLM::Agents::ImageAnalyzer
+      # Default configuration (can be overridden in subclasses)
+      # model "gpt-4o"
+      # analysis_type :detailed
+      # extract_colors false
+      # detect_objects false
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/templates/application_image_editor.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Base class for all image editors in the application
+#
+# Inherits from RubyLLM::Agents::ImageEditor and provides a common
+# foundation for custom image editing classes.
+#
+# @example Creating a custom editor
+#   class BackgroundEditor < ApplicationImageEditor
+#     model "gpt-image-1"
+#     size "1024x1024"
+#     content_policy :strict
+#   end
+#
+class ApplicationImageEditor < RubyLLM::Agents::ImageEditor
+  # Default configuration (can be overridden in subclasses)
+  # model "gpt-image-1"
+  # size "1024x1024"
+  # content_policy :standard
+end

data/lib/generators/ruby_llm_agents/templates/application_image_generator.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Image
+    # Base class for all image generators in the application
+    #
+    # Inherits from RubyLLM::Agents::ImageGenerator and provides a common
+    # foundation for custom image generation classes.
+    #
+    # @example Creating a custom generator
+    #   class LogoGenerator < ApplicationImageGenerator
+    #     model "gpt-image-1"
+    #     size "1024x1024"
+    #     quality "hd"
+    #     style "vivid"
+    #     content_policy :strict
+    #
+    #     template "Professional logo design for {prompt}, minimalist, vector style"
+    #   end
+    #
+    # Usage:
+    #   <%= @root_namespace %>::Image::LogoGenerator.call(prompt: "Company logo")
+    #
+    class ApplicationImageGenerator < RubyLLM::Agents::ImageGenerator
+      # Include ActiveStorage support if available
+      if defined?(ActiveStorage)
+        include RubyLLM::Agents::ImageGenerator::ActiveStorageSupport
+      end
+
+      # Default configuration (can be overridden in subclasses)
+      # model "gpt-image-1"
+      # size "1024x1024"
+      # quality "standard"
+      # style "vivid"
+      # content_policy :standard
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/templates/application_image_pipeline.rb.tt

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Image
+    # ApplicationImagePipeline - Base class for all image pipelines in this application
+    #
+    # All image pipelines inherit from this class. Configure shared settings here
+    # that apply to all pipelines, or override them per-pipeline as needed.
+    #
+    # ============================================================================
+    # IMAGE PIPELINE DSL REFERENCE
+    # ============================================================================
+    #
+    # STEP DEFINITION:
+    # ----------------
+    #   step :name, generator: MyGenerator      # Text-to-image generation
+    #   step :name, upscaler: MyUpscaler        # Resolution enhancement
+    #   step :name, transformer: MyTransformer  # Style transfer / img2img
+    #   step :name, editor: MyEditor            # Inpainting / editing
+    #   step :name, variator: MyVariator        # Generate variations
+    #   step :name, analyzer: MyAnalyzer        # Image analysis (non-image output)
+    #   step :name, remover: MyRemover          # Background removal
+    #
+    # CONDITIONAL STEPS:
+    # ------------------
+    #   step :upscale, upscaler: MyUpscaler, if: ->(ctx) { ctx[:high_quality] }
+    #   step :remove_bg, remover: MyRemover, unless: ->(ctx) { ctx[:keep_background] }
+    #
+    # STEP OPTIONS:
+    # -------------
+    #   step :upscale, upscaler: PhotoUpscaler, scale: 4
+    #   step :transform, transformer: StyleTransformer, strength: 0.8
+    #
+    # CALLBACKS:
+    # ----------
+    #   before_pipeline :validate_inputs
+    #   after_pipeline :add_watermark
+    #   after_pipeline { |result| notify_completion(result) }
+    #
+    # ERROR HANDLING:
+    # ---------------
+    #   stop_on_error true         # Stop pipeline on first error (default)
+    #   stop_on_error false        # Continue even if a step fails
+    #
+    # CACHING:
+    # --------
+    #   cache_for 1.hour           # Cache pipeline results
+    #
+    # METADATA:
+    # ---------
+    #   version "1.0"              # Version identifier (affects cache key)
+    #   description "My pipeline"  # Human-readable description
+    #
+    # ============================================================================
+    # USAGE EXAMPLES
+    # ============================================================================
+    #
+    #   # Simple pipeline
+    #   class ProductPipeline < ApplicationImagePipeline
+    #     step :generate, generator: ProductGenerator
+    #     step :upscale, upscaler: PhotoUpscaler, scale: 2
+    #   end
+    #
+    #   result = ProductPipeline.call(prompt: "Laptop on desk")
+    #   result.final_image    # => URL or data of processed image
+    #   result.total_cost     # => Combined cost of all steps
+    #
+    #   # Pipeline with analysis
+    #   class AnalysisPipeline < ApplicationImagePipeline
+    #     step :generate, generator: ProductGenerator
+    #     step :analyze, analyzer: ContentAnalyzer
+    #   end
+    #
+    #   result = AnalysisPipeline.call(prompt: "Product photo")
+    #   result.analysis       # => ImageAnalysisResult
+    #
+    #   # Conditional pipeline
+    #   class SmartPipeline < ApplicationImagePipeline
+    #     step :generate, generator: ProductGenerator
+    #     step :upscale, upscaler: PhotoUpscaler, if: ->(ctx) { ctx[:hd] }
+    #     step :remove_background, remover: BackgroundRemover, if: ->(ctx) { ctx[:transparent] }
+    #   end
+    #
+    #   result = SmartPipeline.call(prompt: "...", hd: true, transparent: false)
+    #
+    # ============================================================================
+    # RESULT ACCESS
+    # ============================================================================
+    #
+    #   result.success?              # All steps succeeded
+    #   result.partial?              # Some steps succeeded, some failed
+    #   result.error?                # Pipeline failed
+    #
+    #   result.step(:generate)       # Access specific step result
+    #   result.steps                 # Array of all step results
+    #   result.step_count            # Total number of steps
+    #
+    #   result.final_image           # Final processed image (URL or data)
+    #   result.url                   # Final image URL
+    #   result.to_blob               # Final image binary data
+    #   result.save("output.png")    # Save final image to file
+    #
+    #   result.total_cost            # Combined cost of all steps
+    #   result.duration_ms           # Total pipeline duration
+    #
+    class ApplicationImagePipeline < RubyLLM::Agents::ImagePipeline
+      # ============================================
+      # Shared Pipeline Configuration
+      # ============================================
+      # These settings are inherited by all pipelines
+
+      # stop_on_error true  # Stop on first step failure
+
+      # ============================================
+      # Shared Caching
+      # ============================================
+
+      # cache_for 30.minutes  # Enable caching for all pipelines
+
+      # ============================================
+      # Shared Callbacks
+      # ============================================
+      # Define methods here that can be used by all pipelines
+
+      # before_pipeline :validate_tenant
+      # after_pipeline :log_completion
+
+      # private
+
+      # def validate_tenant
+      #   raise ArgumentError, "Tenant required" unless context[:tenant]
+      # end
+
+      # def log_completion(result)
+      #   Rails.logger.info("Pipeline completed: #{result.success?}")
+      # end
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/templates/application_image_transformer.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Base class for all image transformers in the application
+#
+# Inherits from RubyLLM::Agents::ImageTransformer and provides a common
+# foundation for custom image transformation classes.
+#
+# @example Creating a custom transformer
+#   class AnimeTransformer < ApplicationImageTransformer
+#     model "sdxl"
+#     strength 0.8
+#     template "anime style, studio ghibli, {prompt}"
+#   end
+#
+class ApplicationImageTransformer < RubyLLM::Agents::ImageTransformer
+  # Default configuration (can be overridden in subclasses)
+  # model "sdxl"
+  # size "1024x1024"
+  # strength 0.75
+  # preserve_composition true
+end

data/lib/generators/ruby_llm_agents/templates/application_image_upscaler.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Base class for all image upscalers in the application
+#
+# Inherits from RubyLLM::Agents::ImageUpscaler and provides a common
+# foundation for custom image upscaling classes.
+#
+# @example Creating a custom upscaler
+#   class PhotoUpscaler < ApplicationImageUpscaler
+#     model "real-esrgan"
+#     scale 4
+#     face_enhance true
+#   end
+#
+class ApplicationImageUpscaler < RubyLLM::Agents::ImageUpscaler
+  # Default configuration (can be overridden in subclasses)
+  # model "real-esrgan"
+  # scale 4
+  # face_enhance false
+end

data/lib/generators/ruby_llm_agents/templates/application_image_variator.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Base class for all image variators in the application
+#
+# Inherits from RubyLLM::Agents::ImageVariator and provides a common
+# foundation for custom image variation classes.
+#
+# @example Creating a custom variator
+#   class LogoVariator < ApplicationImageVariator
+#     model "gpt-image-1"
+#     size "1024x1024"
+#     variation_strength 0.3
+#   end
+#
+class ApplicationImageVariator < RubyLLM::Agents::ImageVariator
+  # Default configuration (can be overridden in subclasses)
+  # model "gpt-image-1"
+  # size "1024x1024"
+  # variation_strength 0.5
+end

data/lib/generators/ruby_llm_agents/templates/application_speaker.rb.tt

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Audio
+    # ApplicationSpeaker - Base class for all speakers in this application
+    #
+    # All speakers inherit from this class. Configure shared settings here
+    # that apply to all speakers, or override them per-speaker as needed.
+    #
+    # Example:
+    #   class NarratorSpeaker < ApplicationSpeaker
+    #     voice "nova"
+    #     speed 1.1
+    #   end
+    #
+    # Usage:
+    #   <%= @root_namespace %>::Audio::NarratorSpeaker.call(text: "Hello world")
+    #
+    class ApplicationSpeaker < RubyLLM::Agents::Speaker
+      # ============================================
+      # Shared Provider Configuration
+      # ============================================
+      # These settings are inherited by all speakers
+
+      # provider :openai              # TTS provider (:openai, :elevenlabs)
+      # model "tts-1"                 # TTS model
+      # voice "nova"                  # Default voice
+      # speed 1.0                     # Speech speed (0.25-4.0 for OpenAI)
+      # output_format :mp3            # Output format (:mp3, :wav, :ogg, :flac)
+
+      # ============================================
+      # Shared Caching
+      # ============================================
+      # Same text with same settings produces same audio, so caching is effective
+
+      # cache_for 7.days  # Cache generated audio for a week
+
+      # ============================================
+      # Shared Pronunciation Lexicon
+      # ============================================
+      # Define custom pronunciations for technical terms
+
+      # lexicon do
+      #   pronounce 'RubyLLM', 'ruby L L M'
+      #   pronounce 'PostgreSQL', 'post-gres-Q-L'
+      # end
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/templates/application_transcriber.rb.tt

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Audio
+    # ApplicationTranscriber - Base class for all transcribers in this application
+    #
+    # All transcribers inherit from this class. Configure shared settings here
+    # that apply to all transcribers, or override them per-transcriber as needed.
+    #
+    # Example:
+    #   class MeetingTranscriber < ApplicationTranscriber
+    #     language "en"
+    #
+    #     def prompt
+    #       "Business meeting discussion about quarterly results"
+    #     end
+    #   end
+    #
+    # Usage:
+    #   <%= @root_namespace %>::Audio::MeetingTranscriber.call(audio: "meeting.mp3")
+    #
+    class ApplicationTranscriber < RubyLLM::Agents::Transcriber
+      # ============================================
+      # Shared Model Configuration
+      # ============================================
+      # These settings are inherited by all transcribers
+
+      # model "whisper-1"           # Default transcription model
+      # language "en"               # Default language (nil = auto-detect)
+      # output_format :text         # Output format (:text, :srt, :vtt, :json)
+      # include_timestamps :segment # Timestamp granularity (:none, :segment, :word)
+
+      # ============================================
+      # Shared Caching
+      # ============================================
+      # Same audio always produces same transcription, so caching is effective
+
+      # cache_for 30.days  # Cache transcriptions for 30 days
+
+      # ============================================
+      # Shared Post-processing
+      # ============================================
+      # Override in subclass for custom text cleanup
+
+      # def postprocess_text(text)
+      #   text
+      #     .gsub(/\bum\b/i, '')     # Remove filler words
+      #     .gsub(/\buh\b/i, '')
+      #     .squeeze(' ')             # Remove extra spaces
+      # end
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/templates/background_remover.rb.tt

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Image
+<%- if class_name.include?("::") -%>
+<%- class_name.split("::")[0..-2].each_with_index do |mod, i| -%>
+<%= "  " * (i + 2) %>module <%= mod %>
+<%- end -%>
+<%= "  " * (class_name.split("::").length + 1) %>class <%= class_name.split("::").last %>BackgroundRemover < ApplicationBackgroundRemover
+<%- else -%>
+    class <%= class_name %>BackgroundRemover < ApplicationBackgroundRemover
+<%- end -%>
+      # Model configuration
+      model "<%= options[:model] %>"
+      output_format :<%= options[:output_format] %>
+<% if options[:refine_edges] -%>
+      refine_edges true
+<% end -%>
+<% if options[:alpha_matting] -%>
+      alpha_matting true
+<% end -%>
+<% if options[:return_mask] -%>
+      return_mask true
+<% end -%>
+<% if options[:cache] -%>
+
+      # Caching
+      cache_for <%= options[:cache] %>
+<% end -%>
+
+      # Optional: Edge threshold
+      # edge_threshold 0.5
+
+      # Optional: Description
+      # description "Removes backgrounds from <%= class_name.downcase %> images"
+<%- if class_name.include?("::") -%>
+<%- (class_name.split("::").length + 1).times do |i| -%>
+<%= "  " * (class_name.split("::").length + 1 - i) %>end
+<%- end -%>
+<%- else -%>
+    end
+<%- end -%>
+  end
+end

data/lib/generators/ruby_llm_agents/templates/embedder.rb.tt

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Text
+<%- if class_name.include?("::") -%>
+<%- class_name.split("::")[0..-2].each_with_index do |mod, i| -%>
+<%= "  " * (i + 2) %>module <%= mod %>
+<%- end -%>
+<%= "  " * (class_name.split("::").length + 1) %>class <%= class_name.split("::").last %>Embedder < ApplicationEmbedder
+<%- else -%>
+    class <%= class_name %>Embedder < ApplicationEmbedder
+<%- end -%>
+      # Model configuration
+      model "<%= options[:model] %>"
+<% if options[:dimensions] -%>
+      dimensions <%= options[:dimensions] %>
+<% end -%>
+<% if options[:batch_size] != 100 -%>
+      batch_size <%= options[:batch_size] %>
+<% end -%>
+<% if options[:cache] -%>
+
+      # Caching
+      cache_for <%= options[:cache] %>
+<% end -%>
+
+      # Optional: Custom preprocessing
+      # Override this method to normalize/clean text before embedding
+      #
+      # def preprocess(text)
+      #   text.strip.downcase.gsub(/\s+/, ' ')
+      # end
+<%- if class_name.include?("::") -%>
+<%- (class_name.split("::").length + 1).times do |i| -%>
+<%= "  " * (class_name.split("::").length + 1 - i) %>end
+<%- end -%>
+<%- else -%>
+    end
+<%- end -%>
+  end
+end