ruby_llm-agents 0.5.0 → 1.0.0

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

@@ -0,0 +1,45 @@
+# 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 %>Analyzer < ApplicationImageAnalyzer
+<%- else -%>
+    class <%= class_name %>Analyzer < ApplicationImageAnalyzer
+<%- end -%>
+      # Model configuration
+      model "<%= options[:model] %>"
+      analysis_type :<%= options[:analysis_type] %>
+<% if options[:extract_colors] -%>
+      extract_colors true
+<% end -%>
+<% if options[:detect_objects] -%>
+      detect_objects true
+<% end -%>
+<% if options[:extract_text] -%>
+      extract_text true
+<% end -%>
+      max_tags <%= options[:max_tags] %>
+<% if options[:cache] -%>
+
+      # Caching
+      cache_for <%= options[:cache] %>
+<% end -%>
+
+      # Optional: Custom analysis prompt
+      # prompt "Analyze this image and describe..."
+
+      # Optional: Description
+      # description "Analyzes <%= 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/image_editor.rb.tt

@@ -0,0 +1,35 @@
+# 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 %>Editor < ApplicationImageEditor
+<%- else -%>
+    class <%= class_name %>Editor < ApplicationImageEditor
+<%- end -%>
+      # Model configuration
+      model "<%= options[:model] %>"
+      size "<%= options[:size] %>"
+<% if options[:content_policy] != "standard" -%>
+      content_policy :<%= options[:content_policy] %>
+<% end -%>
+<% if options[:cache] -%>
+
+      # Caching
+      cache_for <%= options[:cache] %>
+<% end -%>
+
+      # Optional: Description
+      # description "Edits <%= 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/image_generator.rb.tt

@@ -0,0 +1,47 @@
+# 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 %>Generator < ApplicationImageGenerator
+<%- else -%>
+    class <%= class_name %>Generator < ApplicationImageGenerator
+<%- end -%>
+      # Model configuration
+      model "<%= options[:model] %>"
+      size "<%= options[:size] %>"
+      quality "<%= options[:quality] %>"
+      style "<%= options[:style] %>"
+<% if options[:content_policy] != "standard" -%>
+      content_policy :<%= options[:content_policy] %>
+<% end -%>
+<% if options[:cache] -%>
+
+      # Caching
+      cache_for <%= options[:cache] %>
+<% end -%>
+
+      # Optional: Add a prompt template
+      # template "Professional {prompt}, high quality, detailed"
+
+      # Optional: Add negative prompts (for models that support it)
+      # negative_prompt "blurry, low quality, distorted"
+
+      # Optional: Custom preprocessing
+      # Override this method to modify prompts before generation
+      #
+      # def preprocess_prompt(prompt)
+      #   "#{prompt}, professional quality"
+      # 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

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

@@ -0,0 +1,50 @@
+# 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 %>Pipeline < ApplicationImagePipeline
+<%- else -%>
+    class <%= class_name %>Pipeline < ApplicationImagePipeline
+<%- end -%>
+      # Pipeline steps
+<%- parsed_steps.each do |step| -%>
+<%- case step -%>
+<%- when :generate -%>
+      step :<%= step %>, generator: <%= class_name %>Generator
+<%- when :upscale -%>
+      step :<%= step %>, upscaler: <%= class_name %>Upscaler
+<%- when :transform -%>
+      step :<%= step %>, transformer: <%= class_name %>Transformer
+<%- when :analyze -%>
+      step :<%= step %>, analyzer: <%= class_name %>Analyzer
+<%- when :remove_background -%>
+      step :<%= step %>, remover: <%= class_name %>BackgroundRemover
+<%- else -%>
+      # step :<%= step %>, ...: <%= class_name %><%= step.to_s.camelize %>
+<%- end -%>
+<%- end -%>
+<%- if options[:stop_on_error] == false -%>
+
+      stop_on_error false
+<%- end -%>
+<% if options[:cache] -%>
+
+      # Caching
+      cache_for <%= options[:cache] %>
+<% end -%>
+
+      description "<%= class_name %> image processing pipeline"
+      version "1.0"
+<%- 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/image_transformer.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 %>Transformer < ApplicationImageTransformer
+<%- else -%>
+    class <%= class_name %>Transformer < ApplicationImageTransformer
+<%- end -%>
+      # Model configuration
+      model "<%= options[:model] %>"
+      size "<%= options[:size] %>"
+      strength <%= options[:strength] %>
+<% if options[:content_policy] != "standard" -%>
+      content_policy :<%= options[:content_policy] %>
+<% end -%>
+<% if options[:template] -%>
+
+      # Prompt template
+      template "<%= options[:template] %>"
+<% end -%>
+<% if options[:cache] -%>
+
+      # Caching
+      cache_for <%= options[:cache] %>
+<% end -%>
+
+      # Optional: Negative prompts
+      # negative_prompt "blurry, low quality, distorted"
+
+      # Optional: Description
+      # description "Transforms images into <%= class_name.downcase %> style"
+<%- 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/image_upscaler.rb.tt

@@ -0,0 +1,38 @@
+# 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 %>Upscaler < ApplicationImageUpscaler
+<%- else -%>
+    class <%= class_name %>Upscaler < ApplicationImageUpscaler
+<%- end -%>
+      # Model configuration
+      model "<%= options[:model] %>"
+      scale <%= options[:scale] %>
+<% if options[:face_enhance] -%>
+      face_enhance true
+<% end -%>
+<% if options[:cache] -%>
+
+      # Caching
+      cache_for <%= options[:cache] %>
+<% end -%>
+
+      # Optional: Denoise strength (0.0-1.0)
+      # denoise_strength 0.5
+
+      # Optional: Description
+      # description "Upscales <%= 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/image_variator.rb.tt

@@ -0,0 +1,33 @@
+# 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 %>Variator < ApplicationImageVariator
+<%- else -%>
+    class <%= class_name %>Variator < ApplicationImageVariator
+<%- end -%>
+      # Model configuration
+      model "<%= options[:model] %>"
+      size "<%= options[:size] %>"
+      variation_strength <%= options[:variation_strength] %>
+<% if options[:cache] -%>
+
+      # Caching
+      cache_for <%= options[:cache] %>
+<% end -%>
+
+      # Optional: Description
+      # description "Creates variations of <%= 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/skills/AGENTS.md.tt

@@ -0,0 +1,228 @@
+# <%= @root_namespace %> Agents
+
+This directory contains LLM-powered agents for the application. All agents inherit from `ApplicationAgent`.
+
+## Creating a New Agent
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:agent AgentName param1:required param2:default_value
+```
+
+Or create manually by extending `ApplicationAgent`:
+```ruby
+module <%= @root_namespace %>
+  class MyAgent < ApplicationAgent
+    # Configuration
+    model "gpt-4o"
+    temperature 0.0
+    version "1.0"
+
+    # Parameters
+    param :query, required: true
+    param :limit, default: 10
+
+    private
+
+    def system_prompt
+      "You are a helpful assistant."
+    end
+
+    def user_prompt
+      query
+    end
+  end
+end
+```
+
+## DSL Reference
+
+### Model Configuration
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | LLM model to use | `model "gpt-4o"` |
+| `temperature` | Response randomness (0.0-2.0) | `temperature 0.7` |
+| `version` | Cache invalidation version | `version "2.0"` |
+| `timeout` | Request timeout in seconds | `timeout 30` |
+| `description` | Human-readable description | `description "Searches documents"` |
+
+### Parameters
+
+```ruby
+param :name                          # Optional parameter
+param :query, required: true         # Required parameter
+param :limit, default: 10            # With default value
+param :count, type: Integer          # With type validation
+```
+
+Access parameters as methods: `query`, `limit`, etc.
+
+### Caching
+
+```ruby
+cache 1.hour                         # Enable with TTL
+cache_for 30.minutes                 # Alias for cache
+
+cache_key_includes :user_id, :query  # Only these params in cache key
+cache_key_excludes :timestamp        # Exclude from cache key
+```
+
+### Reliability (Retries & Fallbacks)
+
+```ruby
+# Individual settings
+retries max: 3, backoff: :exponential, base: 0.4, max_delay: 3.0
+fallback_models "gpt-4o-mini", "claude-3-haiku"
+total_timeout 30
+circuit_breaker errors: 5, within: 60, cooldown: 300
+
+# Or grouped in a block
+reliability do
+  retries max: 3, backoff: :exponential
+  fallback_models "gpt-4o-mini"
+  total_timeout 30
+  circuit_breaker errors: 5, within: 60
+end
+```
+
+### Streaming
+
+```ruby
+streaming true  # Enable streaming by default
+```
+
+### Tools
+
+```ruby
+tools [SearchTool, CalculatorTool]  # Make tools available to agent
+```
+
+### Extended Thinking
+
+```ruby
+thinking effort: :high              # Enable extended thinking
+thinking budget: 10000              # With token budget
+```
+
+### Moderation
+
+```ruby
+moderation :input                   # Check input before LLM call
+moderation :output                  # Check output after LLM call
+moderation :both                    # Check both
+```
+
+## Required Methods
+
+### `user_prompt` (required)
+The prompt sent to the LLM. Must return a String.
+
+### `system_prompt` (optional)
+Instructions for the LLM. Return nil for no system prompt.
+
+## Optional Overrides
+
+### `schema`
+Return a `RubyLLM::Schema` for structured JSON output:
+```ruby
+def schema
+  @schema ||= RubyLLM::Schema.create do
+    string :result, description: "The result"
+    integer :confidence, description: "Confidence 1-100"
+    array :tags do
+      string
+    end
+  end
+end
+```
+
+### `process_response(response)`
+Transform the LLM response before returning:
+```ruby
+def process_response(response)
+  content = response.content
+  # Custom processing
+  content
+end
+```
+
+### `messages`
+Provide conversation history for multi-turn:
+```ruby
+def messages
+  [
+    { role: :user, content: "Previous question" },
+    { role: :assistant, content: "Previous answer" }
+  ]
+end
+```
+
+### `cache_key_data`
+Customize what goes into the cache key:
+```ruby
+def cache_key_data
+  { query: query, locale: I18n.locale }
+end
+```
+
+### `execution_metadata`
+Add custom data to execution logs:
+```ruby
+def execution_metadata
+  { request_id: params[:request_id] }
+end
+```
+
+## Calling Agents
+
+```ruby
+# Basic call
+result = <%= @root_namespace %>::MyAgent.call(query: "hello")
+
+# Access result
+result.content          # The response content
+result.input_tokens     # Tokens used in prompt
+result.output_tokens    # Tokens in response
+result.total_cost       # Cost in USD
+
+# Debug mode (no API call)
+result = <%= @root_namespace %>::MyAgent.call(query: "hello", dry_run: true)
+
+# Skip cache
+result = <%= @root_namespace %>::MyAgent.call(query: "hello", skip_cache: true)
+
+# With attachments
+result = <%= @root_namespace %>::MyAgent.call(query: "describe this", with: "image.png")
+
+# Streaming
+<%= @root_namespace %>::MyAgent.stream(query: "hello") do |chunk|
+  print chunk.content
+end
+
+# Multi-tenancy
+result = <%= @root_namespace %>::MyAgent.call(query: "hello", tenant: current_user)
+```
+
+## Testing Agents
+
+```ruby
+RSpec.describe <%= @root_namespace %>::MyAgent do
+  describe ".call" do
+    it "returns expected result" do
+      # Use dry_run for unit tests
+      result = described_class.call(query: "test", dry_run: true)
+      expect(result.content[:user_prompt]).to eq("test")
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep prompts focused** - One agent, one task
+2. **Use structured output** - Define schemas for predictable responses
+3. **Enable caching** - For deterministic queries
+4. **Set appropriate temperatures** - 0.0 for deterministic, higher for creative
+5. **Configure retries** - For production reliability
+6. **Version your agents** - Bump version when changing prompts

data/lib/generators/ruby_llm_agents/templates/skills/BACKGROUND_REMOVERS.md.tt

@@ -0,0 +1,131 @@
+# <%= @root_namespace %>::Image Background Removers
+
+This directory contains background removal services. All removers inherit from `ApplicationBackgroundRemover`.
+
+## Creating a New Remover
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:background_remover RemoverName
+rails generate ruby_llm_agents:background_remover Product --edge_refinement high
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ProductRemover < ApplicationBackgroundRemover
+      model "remove-bg"
+      edge_refinement :high
+      output_format :png
+    end
+  end
+end
+```
+
+## DSL Reference
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | Background removal model | `model "remove-bg"` |
+| `edge_refinement` | Edge quality | `edge_refinement :high` |
+| `output_format` | Output format | `output_format :png` |
+| `background_color` | Replace with color | `background_color "#FFFFFF"` |
+
+### Edge Refinement
+- `:low` - Fastest, rough edges
+- `:medium` - Balanced (default)
+- `:high` - Slow, clean edges
+
+### Output Formats
+- `:png` - Transparent background (default)
+- `:jpg` - With background color
+- `:webp` - Modern format, smaller size
+
+## Using Removers
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductRemover.call(image: "product.jpg")
+
+result.url          # Image URL with transparent background
+result.image_data   # PNG binary data
+result.has_alpha?   # true (has transparency)
+result.save("product_nobg.png")
+```
+
+### With Background Color
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductRemover.call(
+  image: "product.jpg",
+  background_color: "#FFFFFF"  # White background
+)
+```
+
+### Override Settings
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductRemover.call(
+  image: "complex_photo.jpg",
+  edge_refinement: :high,
+  output_format: :webp
+)
+```
+
+## Use Cases
+
+### E-commerce Product Photos
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ProductBackgroundRemover < ApplicationBackgroundRemover
+      edge_refinement :high
+      output_format :png
+
+      cache_for 30.days  # Product images don't change often
+    end
+  end
+end
+```
+
+### Profile Photo Processing
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class AvatarBackgroundRemover < ApplicationBackgroundRemover
+      edge_refinement :high
+      output_format :png
+    end
+  end
+end
+
+# Remove background and resize
+result = <%= @root_namespace %>::Image::AvatarBackgroundRemover.call(image: uploaded_photo)
+```
+
+### Batch Processing
+
+```ruby
+Product.where(background_removed: false).find_each do |product|
+  result = <%= @root_namespace %>::Image::ProductBackgroundRemover.call(
+    image: product.original_image.download
+  )
+
+  product.processed_image.attach(
+    io: StringIO.new(result.image_data),
+    filename: "#{product.id}_nobg.png",
+    content_type: "image/png"
+  )
+  product.update!(background_removed: true)
+end
+```
+
+## Best Practices
+
+1. **Use high edge refinement for products** - Clean edges look professional
+2. **PNG for transparency** - JPG doesn't support alpha
+3. **Cache aggressively** - Same image = same result
+4. **Consider file size** - PNG is larger than JPG
+5. **Test edge cases** - Complex backgrounds, similar colors