ruby_llm-agents 0.5.0 → 1.0.0

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

@@ -0,0 +1,282 @@
+# <%= @root_namespace %>::Image Generators
+
+This directory contains image generation services. All generators inherit from `ApplicationImageGenerator`.
+
+## Creating a New Generator
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:image_generator GeneratorName
+rails generate ruby_llm_agents:image_generator Logo --model gpt-image-1 --size 1024x1024
+rails generate ruby_llm_agents:image_generator Product --quality hd --style vivid
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class LogoGenerator < ApplicationImageGenerator
+      model "gpt-image-1"
+      size "1024x1024"
+      quality "hd"
+      style "vivid"
+      content_policy :standard
+    end
+  end
+end
+```
+
+## DSL Reference
+
+### Model Configuration
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | Image generation model | `model "gpt-image-1"` |
+| `size` | Output image size | `size "1024x1024"` |
+| `quality` | Image quality | `quality "hd"` |
+| `style` | Generation style | `style "vivid"` |
+| `content_policy` | Content filtering level | `content_policy :strict` |
+
+### Available Sizes
+
+- `1024x1024` - Square (default)
+- `1792x1024` - Landscape
+- `1024x1792` - Portrait
+- `512x512` - Small square
+- `256x256` - Thumbnail
+
+### Quality Options
+
+- `standard` - Faster generation, good quality
+- `hd` - Higher detail, slower generation
+
+### Style Options
+
+- `vivid` - Hyper-real, dramatic (default)
+- `natural` - More natural, less extreme
+
+### Content Policy Levels
+
+- `:none` - No filtering
+- `:standard` - Default content filtering
+- `:moderate` - Stricter filtering
+- `:strict` - Maximum filtering
+
+### Caching
+
+```ruby
+cache_for 1.day    # Cache generated images
+cache_for 1.week   # Long-term caching
+```
+
+## Optional Methods & DSL
+
+### `template`
+Define a prompt template:
+
+```ruby
+template "Professional {prompt}, minimalist design, vector art style"
+```
+
+### `negative_prompt`
+Specify what to avoid (for supported models):
+
+```ruby
+negative_prompt "blurry, low quality, distorted, watermark"
+```
+
+### `preprocess_prompt(prompt)`
+Transform prompt before generation:
+
+```ruby
+def preprocess_prompt(prompt)
+  "#{prompt}, professional quality, 8k resolution"
+end
+```
+
+## Using Generators
+
+### Basic Generation
+
+```ruby
+result = <%= @root_namespace %>::Image::LogoGenerator.call(prompt: "Tech startup logo")
+
+result.url          # Temporary URL to generated image
+result.image_data   # Binary image data
+result.size         # "1024x1024"
+result.total_cost   # Cost in USD
+```
+
+### Save to File
+
+```ruby
+result = <%= @root_namespace %>::Image::LogoGenerator.call(prompt: "Company logo")
+result.save("logo.png")
+```
+
+### Generate Multiple Images
+
+```ruby
+result = <%= @root_namespace %>::Image::LogoGenerator.call(
+  prompt: "Product photography",
+  count: 4
+)
+
+result.urls         # Array of image URLs
+result.images       # Array of image data
+```
+
+### Override Settings at Runtime
+
+```ruby
+result = <%= @root_namespace %>::Image::LogoGenerator.call(
+  prompt: "High quality portrait",
+  quality: "hd",
+  size: "1792x1024",
+  style: "natural"
+)
+```
+
+### With ActiveStorage
+
+If ActiveStorage is available:
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductGenerator.call(prompt: "Product shot")
+
+# Attach to a model
+product.images.attach(
+  io: StringIO.new(result.image_data),
+  filename: "product_image.png",
+  content_type: "image/png"
+)
+```
+
+## Use Cases
+
+### Product Photography
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ProductGenerator < ApplicationImageGenerator
+      model "gpt-image-1"
+      size "1024x1024"
+      quality "hd"
+      style "natural"
+
+      template "Professional product photography of {prompt}, " \
+               "white background, studio lighting, e-commerce style"
+
+      negative_prompt "text, watermark, blurry, low quality"
+    end
+  end
+end
+```
+
+### Marketing Banners
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class BannerGenerator < ApplicationImageGenerator
+      model "gpt-image-1"
+      size "1792x1024"  # Landscape
+      quality "hd"
+      style "vivid"
+
+      template "Marketing banner for {prompt}, bold colors, " \
+               "eye-catching design, professional"
+    end
+  end
+end
+```
+
+### Avatar Generation
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class AvatarGenerator < ApplicationImageGenerator
+      model "gpt-image-1"
+      size "512x512"
+      quality "standard"
+      style "vivid"
+      content_policy :strict
+
+      template "Friendly cartoon avatar of {prompt}, " \
+               "professional, approachable, colorful"
+    end
+  end
+end
+```
+
+### Social Media Graphics
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class SocialGenerator < ApplicationImageGenerator
+      model "gpt-image-1"
+      quality "standard"
+
+      def preprocess_prompt(prompt)
+        "#{prompt}, social media post, engaging, modern design"
+      end
+    end
+  end
+end
+
+# Usage with different sizes
+<%= @root_namespace %>::Image::SocialGenerator.call(
+  prompt: "Tech announcement",
+  size: "1024x1024"  # Instagram
+)
+
+<%= @root_namespace %>::Image::SocialGenerator.call(
+  prompt: "Tech announcement",
+  size: "1792x1024"  # Twitter/LinkedIn
+)
+```
+
+## Testing Generators
+
+```ruby
+RSpec.describe <%= @root_namespace %>::Image::LogoGenerator do
+  describe ".call" do
+    it "generates an image" do
+      result = described_class.call(prompt: "Test logo")
+
+      expect(result.url).to be_present
+      expect(result.size).to eq("1024x1024")
+    end
+
+    it "respects quality setting" do
+      result = described_class.call(prompt: "Test", quality: "hd")
+
+      expect(result.quality).to eq("hd")
+    end
+  end
+
+  describe "#preprocess_prompt" do
+    it "enhances the prompt" do
+      generator = described_class.new(prompt: "simple logo")
+
+      result = generator.preprocess_prompt("simple logo")
+
+      expect(result).to include("simple logo")
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Use templates** - Ensure consistent style across generations
+2. **Set appropriate quality** - HD for final assets, standard for drafts
+3. **Use caching** - Same prompt produces same image
+4. **Add negative prompts** - Exclude unwanted elements
+5. **Match size to use case** - Don't generate larger than needed
+6. **Consider content policy** - Use strict for user-facing content
+7. **Handle errors gracefully** - Content policy rejections, rate limits

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

@@ -0,0 +1,228 @@
+# <%= @root_namespace %>::Image Pipelines
+
+This directory contains multi-step image processing pipelines. All pipelines inherit from `ApplicationImagePipeline`.
+
+## Creating a New Pipeline
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:image_pipeline PipelineName
+rails generate ruby_llm_agents:image_pipeline Product --steps generate,upscale,remove_background
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ProductPipeline < ApplicationImagePipeline
+      step :generate, generator: ProductGenerator
+      step :upscale, upscaler: PhotoUpscaler, scale: 2
+      step :remove_bg, remover: BackgroundRemover
+    end
+  end
+end
+```
+
+## DSL Reference
+
+### Step Definition
+
+```ruby
+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
+step :name, remover: MyRemover          # Background removal
+```
+
+### Conditional Steps
+
+```ruby
+step :upscale, upscaler: Upscaler, if: ->(ctx) { ctx[:high_quality] }
+step :remove_bg, remover: Remover, unless: ->(ctx) { ctx[:keep_background] }
+```
+
+### Step Options
+
+```ruby
+step :upscale, upscaler: PhotoUpscaler, scale: 4
+step :transform, transformer: StyleTransformer, strength: 0.8
+```
+
+### Callbacks
+
+```ruby
+before_pipeline :validate_inputs
+after_pipeline :add_watermark
+after_pipeline { |result| notify_completion(result) }
+```
+
+### Error Handling
+
+```ruby
+stop_on_error true   # Stop pipeline on first error (default)
+stop_on_error false  # Continue even if a step fails
+```
+
+### Caching
+
+```ruby
+cache_for 1.hour     # Cache pipeline results
+```
+
+## Using Pipelines
+
+### Basic Execution
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductPipeline.call(prompt: "Laptop on desk")
+
+result.success?       # All steps succeeded
+result.final_image    # Final processed image
+result.url            # Final image URL
+result.total_cost     # Combined cost of all steps
+result.duration_ms    # Total pipeline duration
+```
+
+### Access Individual Steps
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductPipeline.call(prompt: "Product photo")
+
+result.step(:generate)    # Generation step result
+result.step(:upscale)     # Upscale step result
+result.steps              # Array of all step results
+result.step_count         # Total number of steps
+```
+
+### Save Result
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductPipeline.call(prompt: "...")
+result.save("final_output.png")
+```
+
+### Conditional Execution
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class SmartPipeline < ApplicationImagePipeline
+      step :generate, generator: ProductGenerator
+      step :upscale, upscaler: PhotoUpscaler, if: ->(ctx) { ctx[:hd] }
+      step :remove_bg, remover: BackgroundRemover, if: ->(ctx) { ctx[:transparent] }
+    end
+  end
+end
+
+# Call with options
+result = <%= @root_namespace %>::Image::SmartPipeline.call(
+  prompt: "Product photo",
+  hd: true,
+  transparent: false
+)
+```
+
+## Use Cases
+
+### E-commerce Product Pipeline
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class EcommercePipeline < ApplicationImagePipeline
+      description "Generate and process product images"
+      version "1.0"
+
+      step :generate, generator: ProductGenerator
+      step :upscale, upscaler: PhotoUpscaler, scale: 2
+      step :remove_bg, remover: BackgroundRemover
+      step :analyze, analyzer: ProductAnalyzer
+
+      cache_for 1.day
+
+      after_pipeline :log_completion
+
+      private
+
+      def log_completion(result)
+        Rails.logger.info("Pipeline completed: cost=#{result.total_cost}")
+      end
+    end
+  end
+end
+```
+
+### Marketing Asset Pipeline
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class MarketingPipeline < ApplicationImagePipeline
+      step :generate, generator: MarketingGenerator, quality: "hd"
+      step :transform, transformer: BrandStyleTransformer, strength: 0.3
+      step :variations, variator: DesignVariator, count: 4
+
+      stop_on_error false  # Continue even if transform fails
+    end
+  end
+end
+
+result = <%= @root_namespace %>::Image::MarketingPipeline.call(prompt: "Sale banner")
+result.step(:variations).images  # Get all variations
+```
+
+### Photo Enhancement Pipeline
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class EnhancementPipeline < ApplicationImagePipeline
+      step :upscale, upscaler: PhotoUpscaler, scale: 2
+      step :enhance, transformer: EnhancementTransformer, strength: 0.2
+      step :analyze, analyzer: QualityAnalyzer
+
+      before_pipeline :validate_image_format
+
+      private
+
+      def validate_image_format
+        raise ArgumentError, "Image required" unless context[:image]
+      end
+    end
+  end
+end
+
+# Process existing image
+result = <%= @root_namespace %>::Image::EnhancementPipeline.call(image: "photo.jpg")
+```
+
+## Result Methods
+
+```ruby
+result.success?              # All steps succeeded
+result.partial?              # Some steps succeeded
+result.error?                # Pipeline failed
+
+result.final_image           # Final processed image
+result.url                   # Final image URL
+result.to_blob               # Binary data
+result.save("output.png")    # Save to file
+
+result.total_cost            # Combined cost
+result.duration_ms           # Total duration
+result.steps                 # All step results
+result.step(:name)           # Specific step result
+```
+
+## Best Practices
+
+1. **Order steps logically** - Generate before transform, upscale before final
+2. **Use conditional steps** - Skip unnecessary processing
+3. **Enable caching** - Especially for expensive pipelines
+4. **Add callbacks for monitoring** - Log completions, costs
+5. **Set appropriate stop_on_error** - Usually true for production
+6. **Version your pipelines** - Invalidate cache when steps change
+7. **Use analysis steps** - For quality assurance

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

@@ -0,0 +1,120 @@
+# <%= @root_namespace %>::Image Transformers
+
+This directory contains image transformation services (style transfer, img2img). All transformers inherit from `ApplicationImageTransformer`.
+
+## Creating a New Transformer
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:image_transformer TransformerName
+rails generate ruby_llm_agents:image_transformer Style --strength 0.8
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class StyleTransformer < ApplicationImageTransformer
+      model "gpt-image-1"
+      strength 0.7
+      size "1024x1024"
+    end
+  end
+end
+```
+
+## DSL Reference
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | Transformation model | `model "gpt-image-1"` |
+| `strength` | Transformation intensity (0.0-1.0) | `strength 0.7` |
+| `size` | Output size | `size "1024x1024"` |
+
+### Strength Values
+- `0.1-0.3` - Subtle changes, preserve original
+- `0.4-0.6` - Moderate transformation
+- `0.7-0.9` - Strong style transfer
+- `1.0` - Maximum transformation
+
+## Using Transformers
+
+```ruby
+result = <%= @root_namespace %>::Image::StyleTransformer.call(
+  image: "photo.jpg",
+  prompt: "Oil painting style, impressionist"
+)
+
+result.url          # Transformed image URL
+result.image_data   # Binary data
+result.save("transformed.png")
+```
+
+### Override Strength
+
+```ruby
+result = <%= @root_namespace %>::Image::StyleTransformer.call(
+  image: "photo.jpg",
+  prompt: "Watercolor painting",
+  strength: 0.5  # More subtle
+)
+```
+
+## Use Cases
+
+### Artistic Style Transfer
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ArtisticTransformer < ApplicationImageTransformer
+      strength 0.8
+
+      template "{prompt} style, artistic rendering, high quality"
+    end
+  end
+end
+
+# Usage
+<%= @root_namespace %>::Image::ArtisticTransformer.call(
+  image: "photo.jpg",
+  prompt: "Van Gogh starry night"
+)
+```
+
+### Photo Enhancement
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class EnhancementTransformer < ApplicationImageTransformer
+      strength 0.3  # Subtle enhancement
+
+      def default_prompt
+        "Enhanced lighting, improved colors, professional photography"
+      end
+    end
+  end
+end
+```
+
+### Sketch to Photo
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class SketchToPhotoTransformer < ApplicationImageTransformer
+      strength 0.9
+
+      template "Photorealistic version of this sketch: {prompt}"
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Adjust strength carefully** - Start low, increase as needed
+2. **Match styles to content** - Some styles work better with certain images
+3. **Use descriptive prompts** - Specify the desired artistic style
+4. **Consider original quality** - Higher quality inputs produce better results