ruby_llm-agents 0.4.0 → 1.0.0.beta.1

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Migration to create the api_configurations table
+#
+# This table stores API key configurations that can be managed via the dashboard.
+# Supports both global settings and per-tenant overrides.
+#
+# Resolution priority: per-tenant DB > global DB > config file (RubyLLM.configure)
+#
+# Features:
+# - Encrypted storage for all API keys (using Rails encrypted attributes)
+# - Support for all major LLM providers
+# - Custom endpoint configuration
+# - Connection settings
+# - Default model configuration
+#
+# Run with: rails db:migrate
+class CreateRubyLLMAgentsApiConfigurations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :ruby_llm_agents_api_configurations do |t|
+      # Scope type: 'global' or 'tenant'
+      t.string :scope_type, null: false, default: 'global'
+      # Tenant ID when scope_type='tenant'
+      t.string :scope_id
+
+      # === Encrypted API Keys ===
+      # Rails encrypts stores encrypted data in the same-named column
+      # Primary providers
+      t.text :openai_api_key
+      t.text :anthropic_api_key
+      t.text :gemini_api_key
+
+      # Additional providers
+      t.text :deepseek_api_key
+      t.text :mistral_api_key
+      t.text :perplexity_api_key
+      t.text :openrouter_api_key
+      t.text :gpustack_api_key
+      t.text :xai_api_key
+      t.text :ollama_api_key
+
+      # AWS Bedrock
+      t.text :bedrock_api_key
+      t.text :bedrock_secret_key
+      t.text :bedrock_session_token
+      t.string :bedrock_region
+
+      # Google Vertex AI
+      t.text :vertexai_credentials
+      t.string :vertexai_project_id
+      t.string :vertexai_location
+
+      # === Custom Endpoints ===
+      t.string :openai_api_base
+      t.string :gemini_api_base
+      t.string :ollama_api_base
+      t.string :gpustack_api_base
+      t.string :xai_api_base
+
+      # === OpenAI Options ===
+      t.string :openai_organization_id
+      t.string :openai_project_id
+
+      # === Default Models ===
+      t.string :default_model
+      t.string :default_embedding_model
+      t.string :default_image_model
+      t.string :default_moderation_model
+
+      # === Connection Settings ===
+      t.integer :request_timeout
+      t.integer :max_retries
+      t.decimal :retry_interval, precision: 5, scale: 2
+      t.decimal :retry_backoff_factor, precision: 5, scale: 2
+      t.decimal :retry_interval_randomness, precision: 5, scale: 2
+      t.string :http_proxy
+
+      # Whether to inherit from global config for unset values
+      t.boolean :inherit_global_defaults, default: true
+
+      t.timestamps
+    end
+
+    # Ensure unique scope_type + scope_id combinations
+    add_index :ruby_llm_agents_api_configurations, [:scope_type, :scope_id], unique: true, name: 'idx_api_configs_scope'
+
+    # Index for faster tenant lookups
+    add_index :ruby_llm_agents_api_configurations, :scope_id, name: 'idx_api_configs_scope_id'
+  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

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