ruby_llm-agents 0.5.0 → 1.0.0

data/lib/ruby_llm/agents/core/base/moderation_dsl.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # DSL for configuring content moderation on agents
+    #
+    # Provides declarative configuration for moderating user input
+    # and/or LLM output against safety policies.
+    #
+    # @example Basic input moderation
+    #   class MyAgent < ApplicationAgent
+    #     moderation :input
+    #   end
+    #
+    # @example Moderate both input and output
+    #   class MyAgent < ApplicationAgent
+    #     moderation :both
+    #   end
+    #
+    # @example With configuration options
+    #   class MyAgent < ApplicationAgent
+    #     moderation :input,
+    #       model: 'omni-moderation-latest',
+    #       threshold: 0.8,
+    #       categories: [:hate, :violence],
+    #       on_flagged: :raise
+    #   end
+    #
+    # @example Block-based DSL
+    #   class MyAgent < ApplicationAgent
+    #     moderation do
+    #       input enabled: true, threshold: 0.7
+    #       output enabled: true, threshold: 0.9
+    #       model 'omni-moderation-latest'
+    #       categories :hate, :violence
+    #       on_flagged :block
+    #     end
+    #   end
+    #
+    # @api public
+    module ModerationDSL
+      # Configures content moderation for this agent
+      #
+      # @param phases [Array<Symbol>] Phases to moderate (:input, :output, :both)
+      # @param model [String] Moderation model to use
+      # @param threshold [Float] Score threshold (0.0-1.0) for flagging
+      # @param categories [Array<Symbol>] Categories to check
+      # @param on_flagged [Symbol] Action when flagged (:block, :raise, :warn, :log)
+      # @param custom_handler [Symbol] Method name for custom handling
+      # @yield Block for advanced configuration
+      # @return [Hash, nil] The moderation configuration
+      #
+      # @example Simple input moderation
+      #   moderation :input
+      #
+      # @example Input and output moderation
+      #   moderation :input, :output
+      #   # or
+      #   moderation :both
+      #
+      # @example With options
+      #   moderation :input, threshold: 0.8, on_flagged: :raise
+      def moderation(*phases, **options, &block)
+        if block_given?
+          builder = ModerationBuilder.new
+          builder.instance_eval(&block)
+          @moderation_config = builder.config
+        else
+          # Handle :both shorthand
+          phases = [:input, :output] if phases.include?(:both)
+          phases = [:input] if phases.empty?
+
+          @moderation_config = {
+            phases: phases.flatten.map(&:to_sym),
+            model: options[:model],
+            threshold: options[:threshold],
+            categories: options[:categories],
+            on_flagged: options[:on_flagged] || :block,
+            custom_handler: options[:custom_handler]
+          }
+        end
+      end
+
+      # Returns the moderation configuration for this agent
+      #
+      # @return [Hash, nil] The moderation configuration or nil if not configured
+      def moderation_config
+        @moderation_config || inherited_or_default(:moderation_config, nil)
+      end
+
+      # Returns whether moderation is enabled for this agent
+      #
+      # @return [Boolean] true if moderation is configured
+      def moderation_enabled?
+        !!moderation_config
+      end
+
+      private
+
+      def inherited_or_default(method, default)
+        return default unless superclass.respond_to?(method)
+
+        superclass.send(method)
+      end
+    end
+
+    # Builder class for block-based moderation configuration
+    #
+    # @api private
+    class ModerationBuilder
+      attr_reader :config
+
+      def initialize
+        @config = {
+          phases: [],
+          on_flagged: :block
+        }
+      end
+
+      # Enables input moderation
+      #
+      # @param enabled [Boolean] Whether to enable input moderation
+      # @param threshold [Float, nil] Score threshold for input phase
+      # @return [void]
+      def input(enabled: true, threshold: nil)
+        @config[:phases] << :input if enabled
+        @config[:input_threshold] = threshold if threshold
+      end
+
+      # Enables output moderation
+      #
+      # @param enabled [Boolean] Whether to enable output moderation
+      # @param threshold [Float, nil] Score threshold for output phase
+      # @return [void]
+      def output(enabled: true, threshold: nil)
+        @config[:phases] << :output if enabled
+        @config[:output_threshold] = threshold if threshold
+      end
+
+      # Sets the moderation model
+      #
+      # @param model_name [String] Model identifier
+      # @return [void]
+      def model(model_name)
+        @config[:model] = model_name
+      end
+
+      # Sets the global threshold
+      #
+      # @param value [Float] Score threshold (0.0-1.0)
+      # @return [void]
+      def threshold(value)
+        @config[:threshold] = value
+      end
+
+      # Sets categories to check
+      #
+      # @param cats [Array<Symbol>] Category symbols
+      # @return [void]
+      def categories(*cats)
+        @config[:categories] = cats.flatten.map(&:to_sym)
+      end
+
+      # Sets the action when content is flagged
+      #
+      # @param action [Symbol] :block, :raise, :warn, or :log
+      # @return [void]
+      def on_flagged(action)
+        @config[:on_flagged] = action
+      end
+
+      # Sets a custom handler method
+      #
+      # @param method_name [Symbol] Method name to call on the agent
+      # @return [void]
+      def custom_handler(method_name)
+        @config[:custom_handler] = method_name
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/core/base/moderation_execution.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Execution logic for content moderation
+    #
+    # Provides methods to check content against moderation policies
+    # and handle flagged content according to configuration.
+    #
+    # @api private
+    module ModerationExecution
+      # Moderates input text if input moderation is enabled
+      #
+      # @param text [String] Text to moderate
+      # @return [RubyLLM::Moderation, nil] Moderation result or nil if not enabled
+      def moderate_input(text)
+        return nil unless should_moderate?(:input)
+
+        perform_moderation(text, :input)
+      end
+
+      # Moderates output text if output moderation is enabled
+      #
+      # @param text [String] Text to moderate
+      # @return [RubyLLM::Moderation, nil] Moderation result or nil if not enabled
+      def moderate_output(text)
+        return nil unless should_moderate?(:output)
+
+        perform_moderation(text, :output)
+      end
+
+      # Returns whether moderation was blocked
+      #
+      # @return [Boolean] true if content was blocked by moderation
+      def moderation_blocked?
+        @moderation_blocked == true
+      end
+
+      # Returns the phase where moderation blocked content
+      #
+      # @return [Symbol, nil] :input or :output, or nil if not blocked
+      def moderation_blocked_phase
+        @moderation_blocked_phase
+      end
+
+      # Returns all moderation results collected during execution
+      #
+      # @return [Hash{Symbol => RubyLLM::Moderation}] Results keyed by phase
+      def moderation_results
+        @moderation_results || {}
+      end
+
+      private
+
+      # Checks if the given phase should be moderated
+      #
+      # @param phase [Symbol] :input or :output
+      # @return [Boolean] true if this phase should be moderated
+      def should_moderate?(phase)
+        config = resolved_moderation_config
+        return false unless config
+        return false if @options[:moderation] == false
+
+        config[:phases].include?(phase)
+      end
+
+      # Resolves the effective moderation configuration
+      #
+      # Merges class-level configuration with runtime overrides.
+      #
+      # @return [Hash, nil] Resolved configuration or nil if disabled
+      def resolved_moderation_config
+        runtime_config = @options[:moderation]
+        return nil if runtime_config == false
+
+        base_config = self.class.moderation_config
+        return nil unless base_config
+
+        if runtime_config.is_a?(Hash)
+          base_config.merge(runtime_config)
+        else
+          base_config
+        end
+      end
+
+      # Performs moderation on text
+      #
+      # @param text [String] Text to moderate
+      # @param phase [Symbol] :input or :output
+      # @return [RubyLLM::Moderation] The moderation result
+      def perform_moderation(text, phase)
+        config = resolved_moderation_config
+
+        moderation_opts = {}
+        moderation_opts[:model] = config[:model] if config[:model]
+
+        result = RubyLLM.moderate(text, **moderation_opts)
+
+        @moderation_results ||= {}
+        @moderation_results[phase] = result
+
+        record_moderation_execution(result, phase)
+
+        if content_flagged?(result, config, phase)
+          handle_flagged_content(result, config, phase)
+        end
+
+        result
+      end
+
+      # Determines if content should be flagged based on result and config
+      #
+      # @param result [RubyLLM::Moderation] The moderation result
+      # @param config [Hash] Moderation configuration
+      # @param phase [Symbol] :input or :output
+      # @return [Boolean] true if content should be flagged
+      def content_flagged?(result, config, phase)
+        return false unless result.flagged?
+
+        # Check phase-specific or global threshold
+        threshold = config[:"#{phase}_threshold"] || config[:threshold]
+        if threshold
+          max_score = result.category_scores.values.max
+          return false if max_score.nil? || max_score < threshold
+        end
+
+        # Check category filter
+        if config[:categories]&.any?
+          flagged_categories = result.flagged_categories.map { |c| normalize_category(c) }
+          allowed_categories = config[:categories].map { |c| normalize_category(c) }
+          return false if (flagged_categories & allowed_categories).empty?
+        end
+
+        true
+      end
+
+      # Normalizes category names for comparison
+      #
+      # @param category [String, Symbol] Category name
+      # @return [Symbol] Normalized category symbol
+      def normalize_category(category)
+        category.to_s.tr("/", "_").tr("-", "_").downcase.to_sym
+      end
+
+      # Handles flagged content according to configuration
+      #
+      # @param result [RubyLLM::Moderation] The moderation result
+      # @param config [Hash] Moderation configuration
+      # @param phase [Symbol] :input or :output
+      # @return [void]
+      def handle_flagged_content(result, config, phase)
+        # Custom handler takes priority
+        if config[:custom_handler]
+          action = send(config[:custom_handler], result, phase)
+          return if action == :continue
+        end
+
+        on_flagged = config[:on_flagged] || :block
+
+        case on_flagged
+        when :raise
+          raise ModerationError.new(result, phase)
+        when :block
+          @moderation_blocked = true
+          @moderation_blocked_phase = phase
+        when :warn
+          log_moderation_warning(result, phase)
+        when :log
+          log_moderation_info(result, phase)
+        end
+      end
+
+      # Logs a moderation warning
+      #
+      # @param result [RubyLLM::Moderation] The moderation result
+      # @param phase [Symbol] :input or :output
+      # @return [void]
+      def log_moderation_warning(result, phase)
+        return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+        Rails.logger.warn(
+          "[RubyLLM::Agents] Content flagged in #{phase} moderation: " \
+          "#{result.flagged_categories.join(', ')}"
+        )
+      end
+
+      # Logs moderation info
+      #
+      # @param result [RubyLLM::Moderation] The moderation result
+      # @param phase [Symbol] :input or :output
+      # @return [void]
+      def log_moderation_info(result, phase)
+        return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+        Rails.logger.info(
+          "[RubyLLM::Agents] Content flagged in #{phase} moderation: " \
+          "#{result.flagged_categories.join(', ')}"
+        )
+      end
+
+      # Records moderation execution for tracking
+      #
+      # @param result [RubyLLM::Moderation] The moderation result
+      # @param phase [Symbol] :input or :output
+      # @return [void]
+      def record_moderation_execution(result, phase)
+        return unless RubyLLM::Agents.configuration.track_moderation
+        return unless execution_model_available?
+
+        RubyLLM::Agents::Execution.create!(
+          agent_type: self.class.name,
+          execution_type: "moderation",
+          model_id: result.model,
+          input_tokens: 0,
+          output_tokens: 0,
+          total_cost: 0, # Moderation is typically free or very cheap
+          duration_ms: 0,
+          status: result.flagged? ? "flagged" : "passed",
+          metadata: {
+            phase: phase,
+            flagged: result.flagged?,
+            flagged_categories: result.flagged_categories,
+            category_scores: result.category_scores
+          },
+          tenant_id: resolved_tenant_id
+        )
+      rescue StandardError => e
+        Rails.logger.warn("[RubyLLM::Agents] Failed to record moderation: #{e.message}") if defined?(Rails)
+      end
+
+      # Returns the default moderation model
+      #
+      # @return [String] Default moderation model identifier
+      def default_moderation_model
+        RubyLLM::Agents.configuration.default_moderation_model || "omni-moderation-latest"
+      end
+
+      # Builds the text to moderate for input phase
+      #
+      # Combines user prompt content into a single string.
+      #
+      # @return [String] Text to moderate
+      def build_moderation_input
+        prompt = user_prompt
+        if prompt.is_a?(Array)
+          prompt.map { |p| p.is_a?(Hash) ? p[:content] : p.to_s }.join("\n")
+        else
+          prompt.to_s
+        end
+      end
+
+      # Builds a result for blocked moderation
+      #
+      # @param phase [Symbol] :input or :output
+      # @return [Result] Result with moderation blocked status
+      def build_moderation_blocked_result(phase)
+        Result.new(
+          content: nil,
+          status: :"#{phase}_moderation_blocked",
+          moderation_flagged: true,
+          moderation_result: @moderation_results[phase],
+          moderation_phase: phase,
+          agent_class: self.class.name,
+          model_id: model,
+          input_tokens: 0,
+          output_tokens: 0,
+          total_cost: 0,
+          started_at: @execution_started_at,
+          completed_at: Time.current
+        )
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/core/base.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "base/moderation_dsl"
+require_relative "base/moderation_execution"
+
+module RubyLLM
+  module Agents
+    # Base class for LLM-powered conversational agents
+    #
+    # Inherits from BaseAgent to use the middleware pipeline architecture
+    # while adding moderation capabilities for input/output content filtering.
+    #
+    # @example Creating an agent
+    #   class SearchAgent < ApplicationAgent
+    #     model "gpt-4o"
+    #     temperature 0.0
+    #     version "1.0"
+    #     timeout 30
+    #     cache_for 1.hour
+    #
+    #     param :query, required: true
+    #     param :limit, default: 10
+    #
+    #     def system_prompt
+    #       "You are a search assistant..."
+    #     end
+    #
+    #     def user_prompt
+    #       "Search for: #{query}"
+    #     end
+    #   end
+    #
+    # @example With moderation
+    #   class SafeAgent < ApplicationAgent
+    #     moderation :input, :output
+    #     # or
+    #     moderation :both
+    #
+    #     def user_prompt
+    #       query
+    #     end
+    #   end
+    #
+    # @example Calling an agent
+    #   SearchAgent.call(query: "red dress")
+    #   SearchAgent.call(query: "red dress", dry_run: true)    # Debug mode
+    #   SearchAgent.call(query: "red dress", skip_cache: true) # Bypass cache
+    #
+    # @see RubyLLM::Agents::BaseAgent
+    # @api public
+    class Base < BaseAgent
+      extend ModerationDSL
+      include ModerationExecution
+
+      class << self
+        # Returns the agent type for conversation agents
+        #
+        # @return [Symbol] :conversation
+        def agent_type
+          :conversation
+        end
+      end
+
+      # Execute the core LLM call with moderation support
+      #
+      # This extends BaseAgent's execute method to add input and output
+      # moderation checks when configured via the moderation DSL.
+      #
+      # @param context [Pipeline::Context] The execution context
+      # @return [void] Sets context.output with the result
+      def execute(context)
+        @execution_started_at = context.started_at || Time.current
+
+        # Input moderation check (before LLM call)
+        if self.class.moderation_enabled? && should_moderate?(:input)
+          input_text = build_moderation_input
+          moderate_input(input_text)
+
+          if moderation_blocked?
+            context.output = build_moderation_blocked_result(:input)
+            return
+          end
+        end
+
+        # Execute the LLM call via parent
+        client = build_client
+        response = execute_llm_call(client, context)
+        capture_response(response, context)
+        processed_content = process_response(response)
+
+        # Output moderation check (after LLM call)
+        if self.class.moderation_enabled? && should_moderate?(:output)
+          output_text = processed_content.is_a?(String) ? processed_content : processed_content.to_s
+          moderate_output(output_text)
+
+          if moderation_blocked?
+            context.output = build_moderation_blocked_result(:output)
+            return
+          end
+        end
+
+        context.output = build_result(processed_content, response, context)
+      end
+
+      # Returns the resolved tenant ID for tracking
+      #
+      # @return [String, nil] The tenant identifier
+      def resolved_tenant_id
+        tenant = resolve_tenant
+        return nil unless tenant
+
+        tenant.is_a?(Hash) ? tenant[:id]&.to_s : nil
+      end
+
+      private
+
+      # Check if execution model is available for moderation tracking
+      #
+      # @return [Boolean] true if Execution model can be used
+      def execution_model_available?
+        return @execution_model_available if defined?(@execution_model_available)
+
+        @execution_model_available = begin
+          RubyLLM::Agents::Execution.table_exists?
+        rescue StandardError
+          false
+        end
+      end
+    end
+  end
+end
+
+# Load moderation modules after class is defined (they reopen the class)
+require_relative "base/moderation_dsl"
+require_relative "base/moderation_execution"