ruby_llm-agents 0.4.0 → 1.0.0.beta.1

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

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

@@ -0,0 +1,255 @@
+# <%= @root_namespace %>::Text Embedders
+
+This directory contains text embedding services for vector search and semantic similarity. All embedders inherit from `ApplicationEmbedder`.
+
+## Creating a New Embedder
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:embedder EmbedderName
+rails generate ruby_llm_agents:embedder Document --model text-embedding-3-large
+rails generate ruby_llm_agents:embedder Search --dimensions 512 --batch_size 50
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Text
+    class DocumentEmbedder < ApplicationEmbedder
+      model "text-embedding-3-small"
+      dimensions 1536
+      batch_size 100
+      cache_for 1.week
+    end
+  end
+end
+```
+
+## DSL Reference
+
+### Model Configuration
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | Embedding model | `model "text-embedding-3-large"` |
+| `dimensions` | Vector dimensions | `dimensions 512` |
+| `batch_size` | Texts per API call | `batch_size 100` |
+
+### Available Models
+
+**OpenAI:**
+- `text-embedding-3-small` - 1536 dimensions, fastest, cheapest
+- `text-embedding-3-large` - 3072 dimensions, best quality
+- `text-embedding-ada-002` - 1536 dimensions, legacy
+
+**Dimension reduction:** You can reduce dimensions for storage efficiency:
+```ruby
+dimensions 256   # Reduce from default
+dimensions 512   # Good balance of quality/size
+dimensions 1024  # Higher quality
+```
+
+### Caching
+
+```ruby
+cache_for 1.week   # Cache embeddings
+cache_for 30.days  # Long-term caching
+```
+
+## Optional Methods
+
+### `preprocess(text)`
+Normalize text before embedding:
+
+```ruby
+def preprocess(text)
+  text
+    .strip
+    .downcase
+    .gsub(/\s+/, ' ')
+    .truncate(8000)  # Model token limit
+end
+```
+
+## Using Embedders
+
+### Single Text Embedding
+
+```ruby
+result = <%= @root_namespace %>::Text::DocumentEmbedder.call(text: "Hello world")
+
+result.embedding    # [0.123, -0.456, ...] vector array
+result.dimensions   # 1536
+result.model_id     # "text-embedding-3-small"
+result.total_cost   # Cost in USD
+```
+
+### Batch Embedding
+
+Process multiple texts efficiently:
+
+```ruby
+texts = ["Hello world", "Goodbye world", "Ruby programming"]
+result = <%= @root_namespace %>::Text::DocumentEmbedder.call(texts: texts)
+
+result.embeddings   # Array of embedding vectors
+result.count        # 3
+result.total_cost   # Combined cost
+```
+
+### Vector Storage
+
+Store embeddings in PostgreSQL with pgvector:
+
+```ruby
+# Migration
+add_column :documents, :embedding, :vector, limit: 1536
+
+# Model
+class Document < ApplicationRecord
+  has_neighbors :embedding
+end
+
+# Generate and store embedding
+document = Document.find(1)
+result = <%= @root_namespace %>::Text::DocumentEmbedder.call(text: document.content)
+document.update!(embedding: result.embedding)
+```
+
+### Semantic Search
+
+```ruby
+# Embed the query
+query_result = <%= @root_namespace %>::Text::SearchEmbedder.call(text: "ruby web framework")
+
+# Find similar documents
+similar = Document.nearest_neighbors(:embedding, query_result.embedding, distance: "cosine")
+                  .limit(10)
+```
+
+## Use Cases
+
+### Document Embedding
+
+```ruby
+module <%= @root_namespace %>
+  module Text
+    class DocumentEmbedder < ApplicationEmbedder
+      model "text-embedding-3-large"
+      dimensions 1024
+      batch_size 50
+      cache_for 30.days
+
+      def preprocess(text)
+        text
+          .strip
+          .gsub(/\s+/, ' ')
+          .truncate(8000)
+      end
+    end
+  end
+end
+```
+
+### Search Query Embedding
+
+```ruby
+module <%= @root_namespace %>
+  module Text
+    class SearchEmbedder < ApplicationEmbedder
+      model "text-embedding-3-small"
+      dimensions 512
+      cache_for 1.hour  # Queries may repeat
+
+      def preprocess(text)
+        text.strip.downcase
+      end
+    end
+  end
+end
+```
+
+### Code Embedding
+
+```ruby
+module <%= @root_namespace %>
+  module Text
+    class CodeEmbedder < ApplicationEmbedder
+      model "text-embedding-3-large"
+      cache_for 7.days
+
+      def preprocess(text)
+        # Remove comments, normalize whitespace
+        text
+          .gsub(/#.*$/, '')
+          .gsub(/\/\/.*$/, '')
+          .gsub(/\s+/, ' ')
+          .strip
+      end
+    end
+  end
+end
+```
+
+### Batch Processing
+
+```ruby
+# Embed all documents in batches
+Document.find_each(batch_size: 100) do |doc|
+  next if doc.embedding.present?
+
+  result = <%= @root_namespace %>::Text::DocumentEmbedder.call(text: doc.content)
+  doc.update!(embedding: result.embedding)
+end
+
+# Or batch multiple at once
+texts = Document.where(embedding: nil).limit(100).pluck(:id, :content)
+results = <%= @root_namespace %>::Text::DocumentEmbedder.call(texts: texts.map(&:last))
+
+texts.each_with_index do |(id, _), index|
+  Document.find(id).update!(embedding: results.embeddings[index])
+end
+```
+
+## Testing Embedders
+
+```ruby
+RSpec.describe <%= @root_namespace %>::Text::DocumentEmbedder do
+  describe ".call" do
+    it "returns embedding vector" do
+      result = described_class.call(text: "Hello world")
+
+      expect(result.embedding).to be_an(Array)
+      expect(result.dimensions).to eq(1536)
+    end
+
+    it "handles batch embedding" do
+      texts = ["Hello", "World"]
+      result = described_class.call(texts: texts)
+
+      expect(result.embeddings.length).to eq(2)
+    end
+  end
+
+  describe "#preprocess" do
+    it "normalizes text" do
+      embedder = described_class.new(text: "test")
+      text = "  Multiple   Spaces  "
+
+      result = embedder.preprocess(text)
+
+      expect(result).to eq("multiple spaces")
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Use caching** - Same text always produces same embedding
+2. **Choose appropriate dimensions** - Lower for storage, higher for accuracy
+3. **Batch when possible** - More efficient than single calls
+4. **Preprocess consistently** - Same preprocessing for indexing and search
+5. **Match models** - Use same model for indexing and querying
+6. **Consider truncation** - Handle texts longer than model limits
+7. **Use smaller models for search** - Faster query embedding

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

@@ -0,0 +1,120 @@
+# <%= @root_namespace %>::Image Analyzers
+
+This directory contains image analysis services. All analyzers inherit from `ApplicationImageAnalyzer`.
+
+## Creating a New Analyzer
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:image_analyzer AnalyzerName
+rails generate ruby_llm_agents:image_analyzer Product --model gpt-4o
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ProductAnalyzer < ApplicationImageAnalyzer
+      model "gpt-4o"
+      analysis_type :detailed
+      extract_colors true
+      detect_objects true
+    end
+  end
+end
+```
+
+## DSL Reference
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | Vision model | `model "gpt-4o"` |
+| `analysis_type` | Detail level | `analysis_type :detailed` |
+| `extract_colors` | Extract color palette | `extract_colors true` |
+| `detect_objects` | Detect objects in image | `detect_objects true` |
+
+### Analysis Types
+- `:basic` - Quick overview
+- `:detailed` - Comprehensive analysis
+- `:custom` - With custom prompt
+
+## Using Analyzers
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductAnalyzer.call(image: "product.jpg")
+
+result.description   # Text description
+result.objects       # Detected objects
+result.colors        # Color palette
+result.tags          # Suggested tags
+result.total_cost    # Cost in USD
+```
+
+### Analyze URL
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductAnalyzer.call(
+  image: "https://example.com/photo.jpg"
+)
+```
+
+### Custom Analysis Prompt
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class CustomAnalyzer < ApplicationImageAnalyzer
+      model "gpt-4o"
+      analysis_type :custom
+
+      def analysis_prompt
+        "Analyze this image for: composition, lighting, color harmony. " \
+        "Return JSON with scores from 1-10 for each aspect."
+      end
+    end
+  end
+end
+```
+
+## Use Cases
+
+### Content Moderation
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ModerationAnalyzer < ApplicationImageAnalyzer
+      model "gpt-4o"
+
+      def analysis_prompt
+        "Analyze this image for inappropriate content. " \
+        "Return JSON with: safe (boolean), reason (string if unsafe)"
+      end
+    end
+  end
+end
+```
+
+### Product Categorization
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class CategoryAnalyzer < ApplicationImageAnalyzer
+      model "gpt-4o"
+      detect_objects true
+
+      def analysis_prompt
+        "Identify the product category, brand if visible, and condition."
+      end
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Choose appropriate model** - GPT-4o for detailed analysis
+2. **Use structured prompts** - Request JSON for parsing
+3. **Enable object detection** - When identifying items
+4. **Extract colors** - For visual matching/search

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

@@ -0,0 +1,102 @@
+# <%= @root_namespace %>::Image Editors
+
+This directory contains image editing services (inpainting, masked edits). All editors inherit from `ApplicationImageEditor`.
+
+## Creating a New Editor
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:image_editor EditorName
+rails generate ruby_llm_agents:image_editor Background --model gpt-image-1
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class BackgroundEditor < ApplicationImageEditor
+      model "gpt-image-1"
+      size "1024x1024"
+      content_policy :standard
+    end
+  end
+end
+```
+
+## DSL Reference
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | Image editing model | `model "gpt-image-1"` |
+| `size` | Output size | `size "1024x1024"` |
+| `content_policy` | Content filtering | `content_policy :strict` |
+
+## Using Editors
+
+### Basic Edit with Mask
+
+```ruby
+result = <%= @root_namespace %>::Image::BackgroundEditor.call(
+  image: "photo.png",
+  mask: "mask.png",
+  prompt: "Beautiful sunset sky background"
+)
+
+result.url          # Edited image URL
+result.image_data   # Binary data
+result.save("edited.png")
+```
+
+### Edit Specific Area
+
+```ruby
+# Mask should be PNG with transparent areas indicating regions to edit
+result = <%= @root_namespace %>::Image::BackgroundEditor.call(
+  image: original_image,
+  mask: mask_with_transparent_areas,
+  prompt: "Modern city skyline"
+)
+```
+
+## Use Cases
+
+### Background Replacement
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class BackgroundReplacer < ApplicationImageEditor
+      model "gpt-image-1"
+      size "1024x1024"
+
+      def default_prompt
+        "Professional studio background, soft lighting"
+      end
+    end
+  end
+end
+```
+
+### Object Removal
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ObjectRemover < ApplicationImageEditor
+      model "gpt-image-1"
+
+      # Mask covers the object to remove
+      def default_prompt
+        "Seamless continuation of the surrounding area"
+      end
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Create accurate masks** - Transparent areas indicate edit regions
+2. **Match image sizes** - Mask and image should be same dimensions
+3. **Use descriptive prompts** - Be specific about desired result
+4. **PNG format** - Use PNG for mask transparency support