ruby_llm-agents 0.4.0 → 1.0.0.beta.1

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

@@ -0,0 +1,110 @@
+# <%= @root_namespace %>::Image Upscalers
+
+This directory contains image upscaling services. All upscalers inherit from `ApplicationImageUpscaler`.
+
+## Creating a New Upscaler
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:image_upscaler UpscalerName
+rails generate ruby_llm_agents:image_upscaler Photo --scale 4
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class PhotoUpscaler < ApplicationImageUpscaler
+      model "esrgan"
+      scale 4
+      denoise true
+    end
+  end
+end
+```
+
+## DSL Reference
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | Upscaling model | `model "esrgan"` |
+| `scale` | Scale factor (2, 4, 8) | `scale 4` |
+| `denoise` | Apply noise reduction | `denoise true` |
+| `sharpen` | Apply sharpening | `sharpen true` |
+
+### Scale Factors
+- `2` - Double resolution (512x512 -> 1024x1024)
+- `4` - Quadruple resolution (512x512 -> 2048x2048)
+- `8` - 8x resolution (may be slow)
+
+## Using Upscalers
+
+```ruby
+result = <%= @root_namespace %>::Image::PhotoUpscaler.call(image: "small.jpg")
+
+result.url              # Upscaled image URL
+result.image_data       # Binary data
+result.original_size    # "512x512"
+result.upscaled_size    # "2048x2048"
+result.save("large.png")
+```
+
+### Override Scale
+
+```ruby
+result = <%= @root_namespace %>::Image::PhotoUpscaler.call(
+  image: "thumbnail.jpg",
+  scale: 2  # Just double it
+)
+```
+
+## Use Cases
+
+### Thumbnail Enhancement
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ThumbnailUpscaler < ApplicationImageUpscaler
+      scale 4
+      denoise true
+      sharpen true
+    end
+  end
+end
+```
+
+### Print Preparation
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class PrintUpscaler < ApplicationImageUpscaler
+      scale 4
+      denoise false  # Preserve original detail
+    end
+  end
+end
+```
+
+### Avatar Enhancement
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class AvatarUpscaler < ApplicationImageUpscaler
+      scale 2  # Modest upscale
+      denoise true
+      sharpen true
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Choose appropriate scale** - Don't over-upscale
+2. **Enable denoise for low-quality sources** - Helps with compression artifacts
+3. **Sharpen selectively** - Can introduce artifacts
+4. **Consider file size** - Larger images = larger files
+5. **Test with similar images** - Results vary by content type

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

@@ -0,0 +1,120 @@
+# <%= @root_namespace %>::Image Variators
+
+This directory contains image variation services. All variators inherit from `ApplicationImageVariator`.
+
+## Creating a New Variator
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:image_variator VariatorName
+rails generate ruby_llm_agents:image_variator Product --count 4
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class ProductVariator < ApplicationImageVariator
+      model "gpt-image-1"
+      count 4
+      size "1024x1024"
+    end
+  end
+end
+```
+
+## DSL Reference
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | Variation model | `model "gpt-image-1"` |
+| `count` | Number of variations | `count 4` |
+| `size` | Output size | `size "1024x1024"` |
+| `variation_strength` | How different from original | `variation_strength 0.5` |
+
+### Variation Strength
+- `0.1-0.3` - Very similar to original
+- `0.4-0.6` - Moderate differences
+- `0.7-1.0` - Significant variations
+
+## Using Variators
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductVariator.call(image: "product.png")
+
+result.urls         # Array of variation URLs
+result.images       # Array of image data
+result.count        # Number of variations
+result.total_cost   # Combined cost
+```
+
+### Override Count
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductVariator.call(
+  image: "logo.png",
+  count: 8  # Generate 8 variations
+)
+```
+
+### Save All Variations
+
+```ruby
+result = <%= @root_namespace %>::Image::ProductVariator.call(image: "design.png")
+
+result.images.each_with_index do |image_data, i|
+  File.write("variation_#{i}.png", image_data)
+end
+```
+
+## Use Cases
+
+### Design Exploration
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class DesignVariator < ApplicationImageVariator
+      count 6
+      variation_strength 0.5  # Moderate differences
+    end
+  end
+end
+
+# Generate design alternatives
+result = <%= @root_namespace %>::Image::DesignVariator.call(image: "concept.png")
+```
+
+### A/B Testing Assets
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class MarketingVariator < ApplicationImageVariator
+      count 4
+      variation_strength 0.3  # Similar but different
+    end
+  end
+end
+```
+
+### Avatar Options
+
+```ruby
+module <%= @root_namespace %>
+  module Image
+    class AvatarVariator < ApplicationImageVariator
+      count 8
+      size "512x512"
+      variation_strength 0.4
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Start with fewer variations** - Generate more if needed
+2. **Adjust strength for use case** - Subtle for refinement, strong for exploration
+3. **Use high-quality source** - Better input = better variations
+4. **Consider cost** - Each variation costs separately

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

@@ -0,0 +1,212 @@
+# <%= @root_namespace %>::Audio Speakers
+
+This directory contains text-to-speech (TTS) speakers. All speakers inherit from `ApplicationSpeaker`.
+
+## Creating a New Speaker
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:speaker SpeakerName
+rails generate ruby_llm_agents:speaker Narrator --provider openai --voice nova
+rails generate ruby_llm_agents:speaker Podcast --provider elevenlabs --voice Rachel
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class NarratorSpeaker < ApplicationSpeaker
+      provider :openai
+      model "tts-1"
+      voice "nova"
+      speed 1.0
+      output_format :mp3
+    end
+  end
+end
+```
+
+## DSL Reference
+
+### Provider Configuration
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `provider` | TTS provider | `provider :openai` or `provider :elevenlabs` |
+| `model` | TTS model | `model "tts-1"` or `model "tts-1-hd"` |
+| `voice` | Voice to use | `voice "nova"` |
+| `speed` | Speech speed (0.25-4.0) | `speed 1.25` |
+| `output_format` | Audio format | `output_format :mp3` |
+
+### OpenAI Voices
+- `alloy` - Neutral, balanced
+- `echo` - Male, warm
+- `fable` - British, storytelling
+- `onyx` - Male, deep
+- `nova` - Female, friendly
+- `shimmer` - Female, soft
+
+### OpenAI Models
+- `tts-1` - Standard quality, faster
+- `tts-1-hd` - High definition, slower
+
+### ElevenLabs Configuration
+
+```ruby
+class PodcastSpeaker < ApplicationSpeaker
+  provider :elevenlabs
+  model "eleven_multilingual_v2"
+  voice "Rachel"
+
+  voice_settings do
+    stability 0.5
+    similarity_boost 0.75
+    style 0.5
+    speaker_boost true
+  end
+end
+```
+
+### Caching
+
+```ruby
+cache_for 7.days  # Cache audio output
+```
+
+### Custom Pronunciation
+
+```ruby
+lexicon do
+  pronounce 'API', 'A P I'
+  pronounce 'SQL', 'sequel'
+  pronounce 'PostgreSQL', 'post-gres-Q-L'
+  pronounce 'RubyLLM', 'ruby L L M'
+end
+```
+
+## Using Speakers
+
+### Generate Speech
+
+```ruby
+result = <%= @root_namespace %>::Audio::NarratorSpeaker.call(text: "Hello world")
+
+result.audio        # Binary audio data
+result.format       # :mp3
+result.duration     # Duration in seconds (if available)
+result.total_cost   # Cost in USD
+```
+
+### Save to File
+
+```ruby
+result = <%= @root_namespace %>::Audio::NarratorSpeaker.call(text: "Hello world")
+result.save_to("output.mp3")
+```
+
+### Stream Audio
+
+For long text, stream chunks as they're generated:
+
+```ruby
+<%= @root_namespace %>::Audio::NarratorSpeaker.stream(text: long_article) do |chunk|
+  audio_player.play(chunk.audio)
+end
+```
+
+### Override Settings at Runtime
+
+```ruby
+result = <%= @root_namespace %>::Audio::NarratorSpeaker.call(
+  text: "Speak slowly and clearly",
+  voice: "onyx",
+  speed: 0.8
+)
+```
+
+## Use Cases
+
+### Article Narration
+
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class ArticleNarratorSpeaker < ApplicationSpeaker
+      provider :openai
+      model "tts-1-hd"
+      voice "fable"
+      speed 0.9
+
+      cache_for 30.days
+
+      lexicon do
+        pronounce 'JavaScript', 'java-script'
+        pronounce 'TypeScript', 'type-script'
+      end
+    end
+  end
+end
+
+# Usage
+article = Article.find(params[:id])
+result = <%= @root_namespace %>::Audio::ArticleNarratorSpeaker.call(text: article.body)
+result.save_to("public/audio/articles/#{article.id}.mp3")
+```
+
+### Voice Announcements
+
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class AnnouncementSpeaker < ApplicationSpeaker
+      provider :openai
+      voice "nova"
+      speed 1.1
+      output_format :mp3
+    end
+  end
+end
+
+# Usage
+<%= @root_namespace %>::Audio::AnnouncementSpeaker.call(
+  text: "Your order has been shipped!"
+)
+```
+
+### Multilingual TTS
+
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class MultilingualSpeaker < ApplicationSpeaker
+      provider :elevenlabs
+      model "eleven_multilingual_v2"
+      voice "Rachel"
+    end
+  end
+end
+```
+
+## Testing Speakers
+
+```ruby
+RSpec.describe <%= @root_namespace %>::Audio::NarratorSpeaker do
+  describe ".call" do
+    it "generates audio from text" do
+      result = described_class.call(text: "Hello world")
+
+      expect(result.audio).to be_present
+      expect(result.format).to eq(:mp3)
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Use caching** - Same text produces same audio
+2. **Choose appropriate voices** - Match voice to content type
+3. **Add pronunciation lexicon** - For technical terms and acronyms
+4. **Use HD models for quality** - When audio quality matters
+5. **Stream long content** - Don't wait for entire audio to generate
+6. **Consider file sizes** - MP3 is smaller, WAV is lossless

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

@@ -0,0 +1,227 @@
+# <%= @root_namespace %> Tools
+
+This directory contains tools that agents can use to perform actions. Tools allow LLM agents to interact with external systems, APIs, databases, and more.
+
+## Creating a Tool
+
+Tools use the RubyLLM tool interface. Create a class that includes `RubyLLM::Tool`:
+
+```ruby
+module <%= @root_namespace %>
+  class SearchTool
+    include RubyLLM::Tool
+
+    description "Searches the knowledge base for relevant documents"
+
+    param :query, type: :string, description: "The search query", required: true
+    param :limit, type: :integer, description: "Maximum results to return", default: 10
+
+    def execute(query:, limit: 10)
+      # Implement your tool logic here
+      results = Document.search(query).limit(limit)
+
+      results.map do |doc|
+        { title: doc.title, content: doc.content, score: doc.score }
+      end
+    end
+  end
+end
+```
+
+## Tool DSL Reference
+
+### `description`
+Human-readable description of what the tool does. The LLM uses this to decide when to call the tool.
+
+```ruby
+description "Fetches current weather data for a given location"
+```
+
+### `param`
+Define parameters the tool accepts:
+
+```ruby
+param :name, type: :string, description: "Parameter description", required: true
+param :count, type: :integer, description: "Optional count", default: 5
+```
+
+**Supported types:**
+- `:string` - Text values
+- `:integer` - Whole numbers
+- `:number` - Decimal numbers
+- `:boolean` - true/false
+- `:array` - Lists of values
+- `:object` - Nested objects
+
+### `execute`
+The method that runs when the tool is called. Receives keyword arguments matching the defined params.
+
+```ruby
+def execute(query:, limit: 10)
+  # Tool implementation
+  # Return value is passed back to the LLM
+end
+```
+
+## Using Tools with Agents
+
+Register tools in your agent:
+
+```ruby
+module <%= @root_namespace %>
+  class ResearchAgent < ApplicationAgent
+    model "gpt-4o"
+
+    tools [SearchTool, CalculatorTool, WebFetchTool]
+
+    param :question, required: true
+
+    private
+
+    def system_prompt
+      <<~PROMPT
+        You are a research assistant. Use the available tools to answer questions.
+        Always cite your sources.
+      PROMPT
+    end
+
+    def user_prompt
+      question
+    end
+  end
+end
+```
+
+## Tool Patterns
+
+### Database Query Tool
+
+```ruby
+module <%= @root_namespace %>
+  class CustomerLookupTool
+    include RubyLLM::Tool
+
+    description "Looks up customer information by email or ID"
+
+    param :email, type: :string, description: "Customer email address"
+    param :id, type: :integer, description: "Customer ID"
+
+    def execute(email: nil, id: nil)
+      customer = if id
+        Customer.find_by(id: id)
+      elsif email
+        Customer.find_by(email: email)
+      end
+
+      return { error: "Customer not found" } unless customer
+
+      {
+        id: customer.id,
+        name: customer.name,
+        email: customer.email,
+        plan: customer.subscription_plan
+      }
+    end
+  end
+end
+```
+
+### API Integration Tool
+
+```ruby
+module <%= @root_namespace %>
+  class WeatherTool
+    include RubyLLM::Tool
+
+    description "Gets current weather for a location"
+
+    param :city, type: :string, description: "City name", required: true
+    param :units, type: :string, description: "Temperature units (celsius/fahrenheit)", default: "celsius"
+
+    def execute(city:, units: "celsius")
+      response = HTTP.get("https://api.weather.com/current", params: {
+        q: city,
+        units: units == "celsius" ? "metric" : "imperial"
+      })
+
+      data = JSON.parse(response.body)
+
+      {
+        temperature: data["temp"],
+        conditions: data["conditions"],
+        humidity: data["humidity"]
+      }
+    rescue HTTP::Error => e
+      { error: "Failed to fetch weather: #{e.message}" }
+    end
+  end
+end
+```
+
+### Action Tool
+
+```ruby
+module <%= @root_namespace %>
+  class SendEmailTool
+    include RubyLLM::Tool
+
+    description "Sends an email to a recipient"
+
+    param :to, type: :string, description: "Recipient email", required: true
+    param :subject, type: :string, description: "Email subject", required: true
+    param :body, type: :string, description: "Email body content", required: true
+
+    def execute(to:, subject:, body:)
+      # Validate email format
+      unless to.match?(URI::MailTo::EMAIL_REGEXP)
+        return { error: "Invalid email address" }
+      end
+
+      UserMailer.custom_email(to: to, subject: subject, body: body).deliver_later
+
+      { success: true, message: "Email queued for delivery to #{to}" }
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Clear descriptions** - Write descriptions that help the LLM understand when to use the tool
+2. **Validate inputs** - Check parameters before executing
+3. **Handle errors gracefully** - Return error objects instead of raising exceptions
+4. **Keep tools focused** - One tool, one purpose
+5. **Return structured data** - Return hashes that the LLM can interpret
+6. **Consider rate limits** - Add throttling for API-calling tools
+7. **Log tool usage** - Track which tools are called and how often
+
+## Testing Tools
+
+```ruby
+RSpec.describe <%= @root_namespace %>::SearchTool do
+  describe "#execute" do
+    it "returns search results" do
+      tool = described_class.new
+      results = tool.execute(query: "ruby programming", limit: 5)
+
+      expect(results).to be_an(Array)
+      expect(results.length).to be <= 5
+    end
+
+    it "handles empty results" do
+      tool = described_class.new
+      results = tool.execute(query: "xyznonexistent123", limit: 5)
+
+      expect(results).to eq([])
+    end
+  end
+end
+```
+
+## Security Considerations
+
+- **Sanitize inputs** - Never trust LLM-provided parameters directly
+- **Limit scope** - Tools should only access what they need
+- **Audit actions** - Log destructive operations
+- **Rate limit** - Prevent abuse of expensive operations
+- **Validate permissions** - Check user authorization before actions