ruby_llm-agents 0.5.0 → 1.0.0

data/lib/ruby_llm/agents/pipeline/middleware/tenant.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pipeline
+      module Middleware
+        # Resolves tenant context from options and applies API configuration.
+        #
+        # This middleware extracts tenant information from the context options,
+        # sets the tenant_id, tenant_object, and tenant_config on the context,
+        # and applies the resolved API configuration to RubyLLM.
+        #
+        # Supports three formats:
+        # - Object with llm_tenant_id method (recommended for ActiveRecord models)
+        # - Hash with :id key (simple/legacy format)
+        # - nil (no tenant - single-tenant mode)
+        #
+        # API key resolution priority:
+        # 1. Tenant object's llm_api_keys method (if present)
+        # 2. Tenant-specific database config (ApiConfiguration)
+        # 3. Global database config
+        # 4. RubyLLM.configuration (set via initializer or environment)
+        #
+        # @example With ActiveRecord model
+        #   # Model uses llm_tenant DSL
+        #   class Organization < ApplicationRecord
+        #     include RubyLLM::Agents::LLMTenant
+        #     llm_tenant id: :slug, api_keys: { openai: :openai_key }
+        #   end
+        #
+        #   # Pass tenant to agent
+        #   MyAgent.call(query: "test", tenant: organization)
+        #
+        # @example With hash
+        #   MyAgent.call(query: "test", tenant: { id: "org_123" })
+        #
+        # @example Without tenant
+        #   MyAgent.call(query: "test")  # Single-tenant mode
+        #
+        class Tenant < Base
+          # Process tenant resolution and API key application
+          #
+          # @param context [Context] The execution context
+          # @return [Context] The context with tenant fields populated
+          def call(context)
+            resolve_tenant!(context)
+            apply_api_configuration!(context)
+            @app.call(context)
+          end
+
+          private
+
+          # Resolves tenant context from options
+          #
+          # @param context [Context] The execution context
+          # @raise [ArgumentError] If tenant format is invalid
+          def resolve_tenant!(context)
+            tenant_value = context.options[:tenant]
+
+            case tenant_value
+            when nil
+              # No tenant - single-tenant mode
+              context.tenant_id = nil
+              context.tenant_object = nil
+              context.tenant_config = nil
+
+            when Hash
+              # Hash format: { id: "tenant_id", object: tenant, ... }
+              # The :object key is set by BaseAgent.resolve_tenant when tenant object
+              # is passed via tenant: param
+              context.tenant_id = tenant_value[:id]&.to_s
+              context.tenant_object = tenant_value[:object]
+              context.tenant_config = tenant_value.except(:id, :object)
+
+            else
+              # Object with llm_tenant_id method
+              if tenant_value.respond_to?(:llm_tenant_id)
+                context.tenant_id = tenant_value.llm_tenant_id&.to_s
+                context.tenant_object = tenant_value
+                context.tenant_config = extract_tenant_config(tenant_value)
+              else
+                raise ArgumentError,
+                      "tenant must respond to :llm_tenant_id (use llm_tenant DSL), " \
+                      "or be a Hash with :id key, got #{tenant_value.class}"
+              end
+            end
+          end
+
+          # Applies API configuration to RubyLLM based on resolved tenant
+          #
+          # This method resolves API keys from multiple sources and applies
+          # them to RubyLLM.config before the agent executes.
+          #
+          # @param context [Context] The execution context
+          def apply_api_configuration!(context)
+            # First, try to apply keys from tenant object's llm_api_keys method
+            apply_tenant_object_api_keys!(context)
+
+            # Then, apply database configuration (tenant > global > ruby_llm_config)
+            apply_database_api_configuration!(context)
+          end
+
+          # Applies API keys from tenant object's llm_api_keys method
+          #
+          # @param context [Context] The execution context
+          def apply_tenant_object_api_keys!(context)
+            tenant_object = context.tenant_object
+            return unless tenant_object.respond_to?(:llm_api_keys)
+
+            api_keys = tenant_object.llm_api_keys
+            return if api_keys.blank?
+
+            apply_api_keys_to_ruby_llm(api_keys)
+          rescue StandardError => e
+            # Log but don't fail if API key extraction fails
+            warn_api_key_error("tenant object", e)
+          end
+
+          # Applies API configuration from the database
+          #
+          # @param context [Context] The execution context
+          def apply_database_api_configuration!(context)
+            return unless api_configuration_available?
+
+            resolved = ApiConfiguration.resolve(tenant_id: context.tenant_id)
+            resolved.apply_to_ruby_llm!
+
+            # Store resolved config on context for observability
+            context[:resolved_api_config] = resolved
+          rescue StandardError => e
+            # Log but don't fail if DB lookup fails
+            warn_api_key_error("database", e)
+          end
+
+          # Applies a hash of API keys to RubyLLM configuration
+          #
+          # @param api_keys [Hash] Hash of provider => key mappings
+          def apply_api_keys_to_ruby_llm(api_keys)
+            RubyLLM.configure do |config|
+              api_keys.each do |provider, key|
+                next if key.blank?
+
+                setter = api_key_setter_for(provider)
+                config.public_send(setter, key) if config.respond_to?(setter)
+              end
+            end
+          end
+
+          # Returns the setter method name for a provider's API key
+          #
+          # @param provider [Symbol, String] Provider name (e.g., :openai, :anthropic)
+          # @return [String] Setter method name (e.g., "openai_api_key=")
+          def api_key_setter_for(provider)
+            "#{provider}_api_key="
+          end
+
+          # Checks if ApiConfiguration model is available
+          #
+          # @return [Boolean]
+          def api_configuration_available?
+            return false unless defined?(RubyLLM::Agents::ApiConfiguration)
+
+            # Check if table exists
+            ApiConfiguration.table_exists?
+          rescue StandardError
+            false
+          end
+
+          # Logs a warning about API key resolution failure
+          #
+          # @param source [String] Source that failed
+          # @param error [StandardError] The error
+          def warn_api_key_error(source, error)
+            return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+            Rails.logger.warn(
+              "[RubyLLM::Agents] Failed to resolve API keys from #{source}: #{error.message}"
+            )
+          end
+
+          # Extracts additional configuration from tenant object
+          #
+          # @param tenant [Object] The tenant object
+          # @return [Hash, nil] Additional configuration or nil
+          def extract_tenant_config(tenant)
+            return nil unless tenant.respond_to?(:llm_config)
+
+            tenant.llm_config
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/pipeline.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Pipeline infrastructure for middleware-based agent execution
+#
+# The pipeline provides a clean separation of concerns through middleware:
+# - Context: Carries data through the pipeline
+# - Middleware: Wraps execution with cross-cutting concerns
+# - Builder: Constructs the middleware stack
+# - Executor: Adapts agent execution to the pipeline interface
+#
+# @example Basic pipeline usage
+#   # Build a pipeline for an agent class
+#   pipeline = Pipeline::Builder.for(MyEmbedder).build(
+#     Pipeline::Executor.new(agent_instance)
+#   )
+#
+#   # Create a context and execute
+#   context = Pipeline::Context.new(
+#     input: "Hello world",
+#     agent_class: MyEmbedder
+#   )
+#   result_context = pipeline.call(context)
+#
+# @see Pipeline::Context
+# @see Pipeline::Builder
+# @see Pipeline::Middleware::Base
+#
+require_relative "pipeline/context"
+require_relative "pipeline/executor"
+require_relative "pipeline/builder"
+
+# Middleware classes
+require_relative "pipeline/middleware/base"
+require_relative "pipeline/middleware/tenant"
+require_relative "pipeline/middleware/budget"
+require_relative "pipeline/middleware/cache"
+require_relative "pipeline/middleware/instrumentation"
+require_relative "pipeline/middleware/reliability"
+
+module RubyLLM
+  module Agents
+    module Pipeline
+      class << self
+        # Build a pipeline for an agent class with default middleware
+        #
+        # This is a convenience method that combines Builder.for with build.
+        #
+        # @param agent_class [Class] The agent class
+        # @param executor [#call] The core executor
+        # @return [#call] The complete pipeline
+        def build(agent_class, executor)
+          Builder.for(agent_class).build(executor)
+        end
+
+        # Build an empty pipeline (no middleware)
+        #
+        # Useful for testing or when you want direct execution.
+        #
+        # @param agent_class [Class] The agent class
+        # @param executor [#call] The core executor
+        # @return [#call] The executor (no middleware wrapping)
+        def build_empty(agent_class, executor)
+          Builder.empty(agent_class).build(executor)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/{engine.rb → rails/engine.rb}

@@ -32,11 +32,11 @@ module RubyLLM
       #
       # @api private
       config.to_prepare do
-        require_relative "execution_logger_job"
-        require_relative "instrumentation"
-        require_relative "resolved_config"
-        require_relative "base"
-        require_relative "workflow"
+        require_relative "../infrastructure/execution_logger_job"
+        require_relative "../core/instrumentation"
+        require_relative "../core/resolved_config"
+        require_relative "../core/base"
+        require_relative "../workflow/orchestrator"
 
         # Resolve the parent controller class from configuration
         # Default is ActionController::Base, but can be set to inherit from app controllers
@@ -170,16 +170,84 @@ module RubyLLM
         g.factory_bot dir: "spec/factories"
       end
 
-      # Adds the host app's app/agents directory to Rails autoload paths
+      # Adds the host app's LLM directories to Rails autoload paths
       #
-      # This allows agent classes defined in app/agents/ to be automatically
-      # loaded without explicit requires. Must run before set_autoload_paths.
+      # This allows agent classes and other LLM components defined in app/llm/
+      # to be automatically loaded without explicit requires.
+      #
+      # Supports two structures:
+      # 1. New grouped structure: app/llm/agents/, app/llm/tools/, etc.
+      # 2. Legacy flat structure: app/agents/ (for backwards compatibility)
       #
       # @api private
       initializer "ruby_llm_agents.autoload_agents", before: :set_autoload_paths do |app|
-        agents_path = app.root.join("app/agents")
-        if agents_path.exist?
-          Rails.autoloaders.main.push_dir(agents_path.to_s)
+        config = RubyLLM::Agents.configuration
+
+        # Check for new grouped structure (app/llm/*)
+        root_path = app.root.join("app", config.root_directory)
+        if root_path.exist?
+          # Add each configured path that exists
+          config.all_autoload_paths.each do |relative_path|
+            full_path = app.root.join(relative_path)
+            if full_path.exist?
+              # Configure namespace for the path
+              namespace = self.class.namespace_for_path(relative_path, config)
+              if namespace
+                Rails.autoloaders.main.push_dir(full_path.to_s, namespace: namespace)
+              else
+                Rails.autoloaders.main.push_dir(full_path.to_s)
+              end
+            end
+          end
+        else
+          # Fallback to legacy flat structure (app/agents/)
+          agents_path = app.root.join("app/agents")
+          if agents_path.exist?
+            Rails.autoloaders.main.push_dir(agents_path.to_s)
+          end
+        end
+      end
+
+      # Determines the namespace constant for a given path
+      #
+      # @param path [String] Relative path like "app/llm/agents"
+      # @param config [Configuration] Current configuration
+      # @return [Module, nil] Namespace module or nil for top-level
+      # @api private
+      def self.namespace_for_path(path, config)
+        # Parse the path to determine namespace
+        parts = path.split("/")
+        return nil unless parts.length >= 3
+
+        category = parts[2] # e.g., "agents", "audio", "image", "text"
+
+        # Determine the namespace name based on category and root_namespace setting
+        namespace_name = if config.root_namespace.blank?
+          # No root namespace - use category namespace only for audio/image/text
+          case category
+          when "audio", "image", "text"
+            category.camelize # "Audio", "Image", "Text"
+          else
+            nil # Top-level for agents, workflows, tools
+          end
+        else
+          # With root namespace - prefix category with root namespace
+          case category
+          when "audio", "image", "text"
+            "#{config.root_namespace}::#{category.camelize}"
+          else
+            config.root_namespace
+          end
+        end
+
+        return nil if namespace_name.nil?
+
+        # Return the constant, creating intermediate modules if needed
+        namespace_name.constantize
+      rescue NameError
+        # Create the namespace module if it doesn't exist
+        namespace_name.split("::").inject(Object) do |mod, name|
+          mod.const_defined?(name, false) ? mod.const_get(name) : mod.const_set(name, Module.new)
         end
       end
     end

data/lib/ruby_llm/agents/results/background_removal_result.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Result wrapper for background removal operations
+    #
+    # Provides a consistent interface for accessing the extracted foreground,
+    # segmentation mask, and metadata.
+    #
+    # @example Accessing removal result
+    #   result = BackgroundRemover.call(image: "photo.jpg")
+    #   result.url        # => "https://..." (transparent PNG)
+    #   result.has_alpha? # => true
+    #   result.mask       # => Segmentation mask (if requested)
+    #   result.success?   # => true
+    #
+    class BackgroundRemovalResult
+      attr_reader :foreground, :mask, :source_image, :model_id, :output_format,
+                  :alpha_matting, :refine_edges,
+                  :started_at, :completed_at, :tenant_id, :remover_class,
+                  :error_class, :error_message
+
+      # Initialize a new result
+      #
+      # @param foreground [Object] The extracted foreground image
+      # @param mask [Object, nil] The segmentation mask (if requested)
+      # @param source_image [String] The original source image
+      # @param model_id [String] Model used for removal
+      # @param output_format [Symbol] Output format used
+      # @param alpha_matting [Boolean] Whether alpha matting was used
+      # @param refine_edges [Boolean] Whether edge refinement was used
+      # @param started_at [Time] When removal started
+      # @param completed_at [Time] When removal completed
+      # @param tenant_id [String, nil] Tenant identifier
+      # @param remover_class [String] Name of the remover class
+      # @param error_class [String, nil] Error class name if failed
+      # @param error_message [String, nil] Error message if failed
+      def initialize(foreground:, mask:, source_image:, model_id:, output_format:,
+                     alpha_matting:, refine_edges:, started_at:, completed_at:,
+                     tenant_id:, remover_class:, error_class: nil, error_message: nil)
+        @foreground = foreground
+        @mask = mask
+        @source_image = source_image
+        @model_id = model_id
+        @output_format = output_format
+        @alpha_matting = alpha_matting
+        @refine_edges = refine_edges
+        @started_at = started_at
+        @completed_at = completed_at
+        @tenant_id = tenant_id
+        @remover_class = remover_class
+        @error_class = error_class
+        @error_message = error_message
+      end
+
+      # Status helpers
+
+      def success?
+        error_class.nil? && !foreground.nil?
+      end
+
+      def error?
+        !success?
+      end
+
+      # Always single for background removal
+      def single?
+        true
+      end
+
+      def batch?
+        false
+      end
+
+      # Image access (foreground)
+
+      def image
+        foreground
+      end
+
+      def url
+        foreground&.url
+      end
+
+      def urls
+        success? ? [url].compact : []
+      end
+
+      def data
+        foreground&.data
+      end
+
+      def datas
+        success? ? [data].compact : []
+      end
+
+      def base64?
+        foreground&.base64? || false
+      end
+
+      def mime_type
+        foreground&.mime_type || "image/#{output_format}"
+      end
+
+      # Mask access
+
+      def mask?
+        !mask.nil?
+      end
+
+      def mask_url
+        mask&.url
+      end
+
+      def mask_data
+        mask&.data
+      end
+
+      # Check if result has alpha channel (transparency)
+      def has_alpha?
+        return false if error?
+
+        # PNG and WebP support alpha
+        %i[png webp].include?(output_format)
+      end
+
+      # Count (always 1 for removal)
+
+      def count
+        success? ? 1 : 0
+      end
+
+      # Timing
+
+      def duration_ms
+        return 0 unless started_at && completed_at
+        ((completed_at - started_at) * 1000).round
+      end
+
+      # Cost estimation
+
+      def total_cost
+        return 0 if error?
+
+        # Background removal typically has fixed per-image cost
+        ImageGenerator::Pricing.calculate_cost(
+          model_id: model_id,
+          count: 1
+        )
+      end
+
+      # File operations
+
+      def save(path)
+        raise "No foreground image to save" unless foreground
+        foreground.save(path)
+      end
+
+      def save_mask(path)
+        raise "No mask to save" unless mask
+        mask.save(path)
+      end
+
+      def to_blob
+        foreground&.to_blob
+      end
+
+      def mask_blob
+        mask&.to_blob
+      end
+
+      def blobs
+        success? ? [to_blob].compact : []
+      end
+
+      # Serialization
+
+      def to_h
+        {
+          success: success?,
+          url: url,
+          mask_url: mask_url,
+          base64: base64?,
+          mime_type: mime_type,
+          has_alpha: has_alpha?,
+          has_mask: mask?,
+          source_image: source_image,
+          model_id: model_id,
+          output_format: output_format,
+          alpha_matting: alpha_matting,
+          refine_edges: refine_edges,
+          total_cost: total_cost,
+          duration_ms: duration_ms,
+          started_at: started_at&.iso8601,
+          completed_at: completed_at&.iso8601,
+          tenant_id: tenant_id,
+          remover_class: remover_class,
+          error_class: error_class,
+          error_message: error_message
+        }
+      end
+
+      # Caching
+
+      def to_cache
+        {
+          url: url,
+          data: data,
+          mask_url: mask_url,
+          mask_data: mask_data,
+          mime_type: mime_type,
+          model_id: model_id,
+          output_format: output_format,
+          total_cost: total_cost,
+          cached_at: Time.current.iso8601
+        }
+      end
+
+      def self.from_cache(data)
+        CachedBackgroundRemovalResult.new(data)
+      end
+    end
+
+    # Lightweight result for cached removals
+    class CachedBackgroundRemovalResult
+      attr_reader :url, :data, :mask_url, :mask_data, :mime_type, :model_id,
+                  :output_format, :total_cost, :cached_at
+
+      def initialize(data)
+        @url = data[:url]
+        @data = data[:data]
+        @mask_url = data[:mask_url]
+        @mask_data = data[:mask_data]
+        @mime_type = data[:mime_type]
+        @model_id = data[:model_id]
+        @output_format = data[:output_format]
+        @total_cost = data[:total_cost]
+        @cached_at = data[:cached_at]
+      end
+
+      def success?
+        !url.nil? || !data.nil?
+      end
+
+      def error?
+        !success?
+      end
+
+      def cached?
+        true
+      end
+
+      def urls
+        success? ? [url].compact : []
+      end
+
+      def datas
+        success? ? [data].compact : []
+      end
+
+      def base64?
+        !data.nil?
+      end
+
+      def mask?
+        !mask_url.nil? || !mask_data.nil?
+      end
+
+      def has_alpha?
+        %i[png webp].include?(output_format&.to_sym)
+      end
+
+      def count
+        success? ? 1 : 0
+      end
+
+      def single?
+        true
+      end
+
+      def batch?
+        false
+      end
+    end
+  end
+end