ruby_llm-agents 0.4.0 → 1.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d8bfa346ee4010060508948c994bc719f5f1ff40dd2eec3aeb04500f2054341
-  data.tar.gz: 5546ca87104e12ba0522c2a6161ed2917355fb6fffcc7cc6dffd9920963b1037
+  metadata.gz: 34342a67c548fae89c92f0cddb75ad820dfe6a334050f806c1acab9b9b84bf29
+  data.tar.gz: a7d57596ff69a931e28e36ee680976557bc9f704f4d69f2296988226ed3ff9ad
 SHA512:
-  metadata.gz: 391c1202b7bb677337329b5bd5358e9cb5bc4589d37cf48291bb4ff427d8ba1e3e7db99e8787d079ecd2f08382a4aa9940c573ad33c3be2040aa2e6ec21eb353
-  data.tar.gz: 9b1ae37b9ca74f060377d32232a9c26a33e411d285ac658be9508348d75316582aa47e309b85c3258fcaf33a1d5e103fdef2aa1090569b86140b046ee7e975fc
+  metadata.gz: 89f6e9f8c05ef128e2c55652b69f5a6e986499d1811fa5ed4a92958eeea1ad129359e39762a3d72124f83b9b38981201216eb5eb45849d2cb265471b1ed45ee7
+  data.tar.gz: a0d1d64b761f94051b18ad0d79585678b536145a8bdfcc05d22cf4e905a4a913848901e85f3dd2ef37b755f14ceb25372c766219af69fa5f12932c108b9e6086

data/README.md

@@ -1,5 +1,13 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./logo_dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./logo_light.png">
+  <img alt="RubyLLM::Agents" src="./logo_light.png">
+</picture>
+
 # RubyLLM::Agents
 
+> **AI Agents:** For comprehensive documentation optimized for AI consumption, see [LLMS.txt](LLMS.txt)
+
 > **Production-ready Rails engine for building, managing, and monitoring LLM-powered AI agents**
 
 [![Gem Version](https://badge.fury.io/rb/ruby_llm-agents.svg)](https://rubygems.org/gems/ruby_llm-agents)
@@ -22,17 +30,22 @@ Build intelligent AI agents in Ruby with a clean DSL, automatic execution tracki
 
 | Feature | Description | Docs |
 |---------|-------------|------|
-| **Agent DSL** | Declarative configuration with model, temperature, parameters | [Agent DSL](https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL) |
-| **Execution Tracking** | Automatic logging with token usage and cost analytics | [Tracking](https://github.com/adham90/ruby_llm-agents/wiki/Execution-Tracking) |
-| **Cost Analytics** | Track spending by agent, model, and time period | [Analytics](https://github.com/adham90/ruby_llm-agents/wiki/Execution-Tracking) |
-| **Reliability** | Automatic retries, model fallbacks, circuit breakers | [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) |
+| **Agent DSL** | Declarative configuration with model, temperature, parameters, description | [Agent DSL](https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL) |
+| **Execution Tracking** | Automatic logging with token usage, cost analytics, and fallback tracking | [Tracking](https://github.com/adham90/ruby_llm-agents/wiki/Execution-Tracking) |
+| **Cost Analytics** | Track spending by agent, model, tenant, and time period | [Analytics](https://github.com/adham90/ruby_llm-agents/wiki/Execution-Tracking) |
+| **Reliability** | Automatic retries, model fallbacks, circuit breakers with block DSL | [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) |
 | **Budget Controls** | Daily/monthly limits with hard and soft enforcement | [Budgets](https://github.com/adham90/ruby_llm-agents/wiki/Budget-Controls) |
+| **Multi-Tenancy** | Per-tenant API keys, budgets, circuit breakers, and execution isolation | [Multi-Tenancy](https://github.com/adham90/ruby_llm-agents/wiki/Multi-Tenancy) |
 | **Workflows** | Pipelines, parallel execution, conditional routers | [Workflows](https://github.com/adham90/ruby_llm-agents/wiki/Workflows) |
+| **Async/Fiber** | Concurrent execution with Ruby fibers for high-throughput workloads | [Async](https://github.com/adham90/ruby_llm-agents/wiki/Async-Fiber) |
 | **Dashboard** | Real-time Turbo-powered monitoring UI | [Dashboard](https://github.com/adham90/ruby_llm-agents/wiki/Dashboard) |
 | **Streaming** | Real-time response streaming with TTFT tracking | [Streaming](https://github.com/adham90/ruby_llm-agents/wiki/Streaming) |
 | **Conversation History** | Multi-turn conversations with message history | [Conversation History](https://github.com/adham90/ruby_llm-agents/wiki/Conversation-History) |
 | **Attachments** | Images, PDFs, and multimodal support | [Attachments](https://github.com/adham90/ruby_llm-agents/wiki/Attachments) |
 | **PII Redaction** | Automatic sensitive data protection | [Security](https://github.com/adham90/ruby_llm-agents/wiki/PII-Redaction) |
+| **Content Moderation** | Input/output safety checks with OpenAI moderation API | [Moderation](https://github.com/adham90/ruby_llm-agents/wiki/Moderation) |
+| **Embeddings** | Vector embeddings with batching, caching, and preprocessing | [Embeddings](https://github.com/adham90/ruby_llm-agents/wiki/Embeddings) |
+| **Image Operations** | Generation, analysis, editing, pipelines with cost tracking | [Images](https://github.com/adham90/ruby_llm-agents/wiki/Image-Generation) |
 | **Alerts** | Slack, webhook, and custom notifications | [Alerts](https://github.com/adham90/ruby_llm-agents/wiki/Alerts) |
 
 ## Quick Start
@@ -66,21 +79,23 @@ rails generate ruby_llm_agents:agent SearchIntent query:required
 ```
 
 ```ruby
-# app/agents/search_intent_agent.rb
-class SearchIntentAgent < ApplicationAgent
-  model "gpt-4o"
-  temperature 0.0
+# app/llm/agents/search_intent_agent.rb
+module LLM
+  class SearchIntentAgent < ApplicationAgent
+    model "gpt-4o"
+    temperature 0.0
 
-  param :query, required: true
+    param :query, required: true
 
-  def user_prompt
-    "Extract search intent from: #{query}"
-  end
+    def user_prompt
+      "Extract search intent from: #{query}"
+    end
 
-  def schema
-    @schema ||= RubyLLM::Schema.create do
-      string :refined_query, description: "Cleaned search query"
-      array :filters, of: :string, description: "Extracted filters"
+    def schema
+      @schema ||= RubyLLM::Schema.create do
+        string :refined_query, description: "Cleaned search query"
+        array :filters, of: :string, description: "Extracted filters"
+      end
     end
   end
 end
@@ -89,7 +104,7 @@ end
 ### Call the Agent
 
 ```ruby
-result = SearchIntentAgent.call(query: "red summer dress under $50")
+result = LLM::SearchIntentAgent.call(query: "red summer dress under $50")
 
 result.content        # => { refined_query: "red dress", filters: ["color:red", "price:<50"] }
 result.total_cost     # => 0.00025
@@ -114,15 +129,126 @@ result = ChatAgent.call(
 
 See [Conversation History](https://github.com/adham90/ruby_llm-agents/wiki/Conversation-History) for more patterns.
 
+### Embeddings
+
+Generate vector embeddings for semantic search, RAG, and similarity matching:
+
+```bash
+rails generate ruby_llm_agents:embedder Document
+```
+
+```ruby
+# app/llm/text/embedders/document_embedder.rb
+module LLM
+  module Text
+    class DocumentEmbedder < ApplicationEmbedder
+      model "text-embedding-3-small"
+      dimensions 512
+      batch_size 100
+      cache_for 1.week
+
+      # Optional: preprocess text before embedding
+      def preprocess(text)
+        text.strip.downcase.gsub(/\s+/, ' ')
+      end
+    end
+  end
+end
+```
+
+```ruby
+# Single text embedding
+result = LLM::Text::DocumentEmbedder.call(text: "Hello world")
+result.vector       # => [0.123, -0.456, ...]
+result.dimensions   # => 512
+result.total_tokens # => 2
+
+# Batch embedding
+result = LLM::Text::DocumentEmbedder.call(texts: ["Hello", "World", "Ruby"])
+result.vectors      # => [[...], [...], [...]]
+result.count        # => 3
+
+# With progress callback for large batches
+LLM::Text::DocumentEmbedder.call(texts: large_array) do |batch_result, index|
+  puts "Processed batch #{index + 1}"
+end
+```
+
+Features:
+- **Configurable dimensions** - Reduce dimensions for efficient storage
+- **Batch processing** - Embed multiple texts in optimized API calls
+- **Caching** - Cache embeddings to reduce API costs
+- **Preprocessing** - Clean and normalize text before embedding
+- **Execution tracking** - All embeddings logged with tokens and costs
+
+See [Embeddings](https://github.com/adham90/ruby_llm-agents/wiki/Embeddings) for more patterns.
+
+### Image Operations
+
+Comprehensive image capabilities with generation, analysis, editing, and pipelines:
+
+```bash
+# Generate image generators, analyzers, pipelines, and more
+rails generate ruby_llm_agents:image_generator Logo
+rails generate ruby_llm_agents:image_analyzer Product
+rails generate ruby_llm_agents:background_remover Photo
+rails generate ruby_llm_agents:image_pipeline Ecommerce --steps generate,upscale,analyze
+```
+
+```ruby
+# Image Generation - create images from prompts
+result = LLM::Image::LogoGenerator.call(prompt: "tech startup logo")
+result.url          # => "https://..."
+result.save("logo.png")
+
+# Image Analysis - extract captions, tags, objects, colors
+result = LLM::Image::ProductAnalyzer.call(image: "product.jpg")
+result.caption      # => "Red sneaker on white background"
+result.tags         # => ["sneaker", "red", "footwear"]
+result.colors       # => [{ hex: "#FF0000", percentage: 30 }]
+
+# Background Removal - extract subjects with transparency
+result = LLM::Image::PhotoBackgroundRemover.call(image: "portrait.jpg")
+result.save("portrait_transparent.png")
+
+# Image Pipelines - chain multiple operations
+result = LLM::Image::EcommercePipeline.call(
+  prompt: "professional laptop photo",
+  high_quality: true
+)
+result.final_image   # => Final processed image
+result.total_cost    # => Combined cost of all steps
+result.step(:analyze).tags  # => Access individual step results
+```
+
+Features:
+- **8 image operation classes** - Generator, Analyzer, Editor, Transformer, Upscaler, Variator, BackgroundRemover, Pipeline
+- **Prompt templates** - Consistent styling with preset templates
+- **Content policy** - Validate prompts with configurable safety levels
+- **Cost tracking** - Dynamic pricing with execution logging
+- **Image Pipelines** - Chain operations into automated workflows
+- **ActiveStorage** - Attach images directly to Rails models
+
+See [Image Operations](https://github.com/adham90/ruby_llm-agents/wiki/Image-Generation) for full documentation.
+
 ## Documentation
 
+> **Note:** Wiki content lives in the [`wiki/`](wiki/) folder. To sync changes to the [GitHub Wiki](https://github.com/adham90/ruby_llm-agents/wiki), run `./scripts/sync-wiki.sh`.
+
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](https://github.com/adham90/ruby_llm-agents/wiki/Getting-Started) | Installation, configuration, first agent |
-| [Agent DSL](https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL) | All DSL options: model, temperature, params, caching |
-| [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) | Retries, fallbacks, circuit breakers, timeouts |
+| [Agent DSL](https://github.com/adham90/ruby_llm-agents/wiki/Agent-DSL) | All DSL options: model, temperature, params, caching, description |
+| [Reliability](https://github.com/adham90/ruby_llm-agents/wiki/Reliability) | Retries, fallbacks, circuit breakers, timeouts, reliability block |
 | [Workflows](https://github.com/adham90/ruby_llm-agents/wiki/Workflows) | Pipelines, parallel execution, routers |
 | [Budget Controls](https://github.com/adham90/ruby_llm-agents/wiki/Budget-Controls) | Spending limits, alerts, enforcement |
+| [Multi-Tenancy](https://github.com/adham90/ruby_llm-agents/wiki/Multi-Tenancy) | Per-tenant budgets, isolation, configuration |
+| [Async/Fiber](https://github.com/adham90/ruby_llm-agents/wiki/Async-Fiber) | Concurrent execution with Ruby fibers |
+| [Testing Agents](https://github.com/adham90/ruby_llm-agents/wiki/Testing-Agents) | RSpec patterns, mocking, dry_run mode |
+| [Error Handling](https://github.com/adham90/ruby_llm-agents/wiki/Error-Handling) | Error types, recovery patterns |
+| [Moderation](https://github.com/adham90/ruby_llm-agents/wiki/Moderation) | Content moderation for input/output safety |
+| [Embeddings](https://github.com/adham90/ruby_llm-agents/wiki/Embeddings) | Vector embeddings, batching, caching, preprocessing |
+| [Image Generation](https://github.com/adham90/ruby_llm-agents/wiki/Image-Generation) | Text-to-image, templates, content policy, cost tracking |
 | [Dashboard](https://github.com/adham90/ruby_llm-agents/wiki/Dashboard) | Setup, authentication, analytics |
 | [Production](https://github.com/adham90/ruby_llm-agents/wiki/Production-Deployment) | Deployment best practices, background jobs |
 | [API Reference](https://github.com/adham90/ruby_llm-agents/wiki/API-Reference) | Complete class documentation |
@@ -133,27 +259,55 @@ See [Conversation History](https://github.com/adham90/ruby_llm-agents/wiki/Conve
 Build resilient agents with built-in fault tolerance:
 
 ```ruby
-class ReliableAgent < ApplicationAgent
-  model "gpt-4o"
+# app/llm/agents/reliable_agent.rb
+module LLM
+  class ReliableAgent < ApplicationAgent
+    model "gpt-4o"
+    description "A resilient agent with automatic retries and fallbacks"
+
+    # Option 1: Individual DSL methods
+    retries max: 3, backoff: :exponential
+    fallback_models "gpt-4o-mini", "claude-3-5-sonnet"
+    circuit_breaker errors: 10, within: 60, cooldown: 300
+    total_timeout 30
+
+    # Option 2: Grouped reliability block (equivalent to above)
+    reliability do
+      retries max: 3, backoff: :exponential
+      fallback_models "gpt-4o-mini", "claude-3-5-sonnet"
+      circuit_breaker errors: 10, within: 60, cooldown: 300
+      total_timeout 30
+    end
 
-  # Retry on failures with exponential backoff
-  retries max: 3, backoff: :exponential
+    param :query, required: true
 
-  # Fall back to alternative models
-  fallback_models "gpt-4o-mini", "claude-3-5-sonnet"
+    def user_prompt
+      query
+    end
+  end
+end
+```
 
-  # Prevent cascading failures
-  circuit_breaker errors: 10, within: 60, cooldown: 300
+### Enhanced Result Object
 
-  # Maximum time for all attempts
-  total_timeout 30
+The result object provides detailed execution metadata:
 
-  param :query, required: true
+```ruby
+result = LLM::ReliableAgent.call(query: "test")
 
-  def user_prompt
-    query
-  end
-end
+# Basic response
+result.content           # => { ... }
+result.success?          # => true
+
+# Reliability info
+result.attempts_count    # => 2 (if retry occurred)
+result.used_fallback?    # => true (if fallback model used)
+result.chosen_model_id   # => "gpt-4o-mini" (actual model used)
+
+# Cost & timing
+result.total_cost        # => 0.00025
+result.total_tokens      # => 150
+result.duration_ms       # => 850
 ```
 
 ## Workflow Orchestration
@@ -200,6 +354,43 @@ result = SupportRouter.call(message: user_input)
 result.routed_to  # :support, :sales, or :default
 ```
 
+## Async/Fiber Concurrency
+
+Run multiple agents concurrently with minimal resources using Ruby's Fiber scheduler:
+
+```ruby
+# Add async gem to Gemfile
+gem 'async'
+```
+
+```ruby
+require 'async'
+
+# Run agents concurrently - non-blocking I/O
+Async do
+  results = RubyLLM::Agents::Async.batch([
+    [SentimentAgent, { input: "I love this!" }],
+    [SummaryAgent, { input: "Long text..." }],
+    [CategoryAgent, { input: "Product review" }]
+  ], max_concurrent: 10)
+end
+
+# Process large collections efficiently
+Async do
+  results = RubyLLM::Agents::Async.each(texts, max_concurrent: 20) do |text|
+    AnalyzerAgent.call(input: text)
+  end
+end
+```
+
+Benefits:
+- **100x less memory** - Fibers use ~10KB vs ~1MB per thread
+- **Shared connections** - Single database connection for all fibers
+- **Auto-detection** - Parallel workflows automatically use fibers in async context
+- **Non-blocking retries** - Backoff delays don't block other operations
+
+See [Async/Fiber](https://github.com/adham90/ruby_llm-agents/wiki/Async-Fiber) for more patterns.
+
 ## Cost & Budget Controls
 
 Track and limit LLM spending:

data/app/controllers/ruby_llm/agents/agents_controller.rb

@@ -30,6 +30,16 @@ module RubyLLM
         @agents = all_items.reject { |a| a[:is_workflow] }
         @workflows = all_items.select { |a| a[:is_workflow] }
 
+        # Group agents by type for sub-tabs
+        @agents_by_type = {
+          agent: @agents.select { |a| a[:agent_type] == "agent" },
+          embedder: @agents.select { |a| a[:agent_type] == "embedder" },
+          moderator: @agents.select { |a| a[:agent_type] == "moderator" },
+          speaker: @agents.select { |a| a[:agent_type] == "speaker" },
+          transcriber: @agents.select { |a| a[:agent_type] == "transcriber" },
+          image_generator: @agents.select { |a| a[:agent_type] == "image_generator" }
+        }
+
         # Group workflows by type for sub-tabs
         @workflows_by_type = {
           pipeline: @workflows.select { |w| w[:workflow_type] == "pipeline" },
@@ -44,6 +54,7 @@ module RubyLLM
         Rails.logger.error("[RubyLLM::Agents] Error loading agents: #{e.message}")
         @agents = []
         @workflows = []
+        @agents_by_type = { agent: [], embedder: [], moderator: [], speaker: [], transcriber: [], image_generator: [] }
         @workflows_by_type = { pipeline: [], parallel: [], router: [] }
         @agent_count = 0
         @workflow_count = 0
@@ -69,7 +80,8 @@ module RubyLLM
 
         if @agent_class
           load_agent_config
-          load_circuit_breaker_status
+          # Only load circuit breaker status for base agents
+          load_circuit_breaker_status if @agent_type_kind == "agent"
         end
       rescue StandardError => e
         Rails.logger.error("[RubyLLM::Agents] Error loading agent #{@agent_type}: #{e.message}")
@@ -207,26 +219,134 @@ module RubyLLM
       #
       # Extracts DSL-configured values from the agent class for display.
       # Only called if the agent class still exists.
+      # Detects agent type and loads appropriate config.
       #
       # @return [void]
       def load_agent_config
+        @agent_type_kind = AgentRegistry.send(:detect_agent_type, @agent_class)
+
+        # Common config for all types
         @config = {
-          # Basic configuration
-          model: @agent_class.model,
-          temperature: @agent_class.temperature,
-          version: @agent_class.version,
-          description: @agent_class.respond_to?(:description) ? @agent_class.description : nil,
-          timeout: @agent_class.timeout,
-          cache_enabled: @agent_class.cache_enabled?,
-          cache_ttl: @agent_class.cache_ttl,
-          params: @agent_class.params,
-
-          # Reliability configuration
-          retries: @agent_class.retries,
-          fallback_models: @agent_class.fallback_models,
-          total_timeout: @agent_class.total_timeout,
-          circuit_breaker: @agent_class.circuit_breaker_config
+          model: safe_config_call(:model),
+          version: safe_config_call(:version) || "N/A",
+          description: safe_config_call(:description)
         }
+
+        # Type-specific config
+        case @agent_type_kind
+        when "embedder"
+          load_embedder_config
+        when "moderator"
+          load_moderator_config
+        when "speaker"
+          load_speaker_config
+        when "transcriber"
+          load_transcriber_config
+        when "image_generator"
+          load_image_generator_config
+        else
+          load_base_agent_config
+        end
+      end
+
+      # Loads configuration specific to Base agents
+      #
+      # @return [void]
+      def load_base_agent_config
+        @config.merge!(
+          temperature: safe_config_call(:temperature),
+          timeout: safe_config_call(:timeout),
+          cache_enabled: safe_config_call(:cache_enabled?) || false,
+          cache_ttl: safe_config_call(:cache_ttl),
+          params: safe_config_call(:params) || {},
+          retries: safe_config_call(:retries),
+          fallback_models: safe_config_call(:fallback_models),
+          total_timeout: safe_config_call(:total_timeout),
+          circuit_breaker: safe_config_call(:circuit_breaker_config)
+        )
+      end
+
+      # Loads configuration specific to Embedders
+      #
+      # @return [void]
+      def load_embedder_config
+        @config.merge!(
+          dimensions: safe_config_call(:dimensions),
+          batch_size: safe_config_call(:batch_size),
+          cache_enabled: safe_config_call(:cache_enabled?) || false,
+          cache_ttl: safe_config_call(:cache_ttl)
+        )
+      end
+
+      # Loads configuration specific to Moderators
+      #
+      # @return [void]
+      def load_moderator_config
+        @config.merge!(
+          threshold: safe_config_call(:threshold),
+          categories: safe_config_call(:categories)
+        )
+      end
+
+      # Loads configuration specific to Speakers
+      #
+      # @return [void]
+      def load_speaker_config
+        @config.merge!(
+          provider: safe_config_call(:provider),
+          voice: safe_config_call(:voice),
+          voice_id: safe_config_call(:voice_id),
+          speed: safe_config_call(:speed),
+          output_format: safe_config_call(:output_format),
+          streaming: safe_config_call(:streaming?),
+          ssml_enabled: safe_config_call(:ssml_enabled?),
+          cache_enabled: safe_config_call(:cache_enabled?) || false,
+          cache_ttl: safe_config_call(:cache_ttl)
+        )
+      end
+
+      # Loads configuration specific to Transcribers
+      #
+      # @return [void]
+      def load_transcriber_config
+        @config.merge!(
+          language: safe_config_call(:language),
+          output_format: safe_config_call(:output_format),
+          include_timestamps: safe_config_call(:include_timestamps),
+          cache_enabled: safe_config_call(:cache_enabled?) || false,
+          cache_ttl: safe_config_call(:cache_ttl),
+          fallback_models: safe_config_call(:fallback_models)
+        )
+      end
+
+      # Loads configuration specific to ImageGenerators
+      #
+      # @return [void]
+      def load_image_generator_config
+        @config.merge!(
+          size: safe_config_call(:size),
+          quality: safe_config_call(:quality),
+          style: safe_config_call(:style),
+          content_policy: safe_config_call(:content_policy),
+          template: safe_config_call(:template_string),
+          negative_prompt: safe_config_call(:negative_prompt),
+          seed: safe_config_call(:seed),
+          guidance_scale: safe_config_call(:guidance_scale),
+          steps: safe_config_call(:steps),
+          cache_enabled: safe_config_call(:cache_enabled?) || false,
+          cache_ttl: safe_config_call(:cache_ttl)
+        )
+      end
+
+      # Safely calls a method on the agent class, returning nil on error
+      #
+      # @param method [Symbol] The method to call
+      # @return [Object, nil] The result or nil if error
+      def safe_config_call(method)
+        return nil unless @agent_class&.respond_to?(method)
+        @agent_class.public_send(method)
+      rescue StandardError
+        nil
       end
 
       # Loads circuit breaker status for the agent's models