ruby_llm-agents 1.3.3 → 2.0.0

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

@@ -1,274 +0,0 @@
-# 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/resolved_config.rb

@@ -1,348 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    # Resolves API configuration with priority chain
-    #
-    # Resolution order:
-    # 1. Tenant-specific database config (if tenant_id provided)
-    # 2. Global database config
-    # 3. RubyLLM.configuration (set via initializer or environment)
-    #
-    # This class provides a unified interface for accessing configuration
-    # values regardless of their source, and can apply the resolved
-    # configuration to RubyLLM.
-    #
-    # @example Basic resolution
-    #   resolved = ResolvedConfig.new(
-    #     tenant_config: ApiConfiguration.for_tenant("acme"),
-    #     global_config: ApiConfiguration.global,
-    #     ruby_llm_config: RubyLLM.configuration
-    #   )
-    #
-    #   resolved.openai_api_key     # => Returns from highest priority source
-    #   resolved.source_for(:openai_api_key)  # => "tenant:acme"
-    #
-    # @example Applying to RubyLLM
-    #   resolved.apply_to_ruby_llm!  # Applies all resolved values
-    #
-    # @see ApiConfiguration
-    # @api public
-    class ResolvedConfig
-      # Returns all resolvable attributes (API keys + settings)
-      # Lazy-loaded to avoid circular dependency with ApiConfiguration
-      #
-      # @return [Array<Symbol>]
-      def self.resolvable_attributes
-        @resolvable_attributes ||= (
-          ApiConfiguration::API_KEY_ATTRIBUTES +
-          ApiConfiguration::NON_KEY_ATTRIBUTES
-        ).freeze
-      end
-
-      # @return [ApiConfiguration, nil] Tenant-specific configuration
-      attr_reader :tenant_config
-
-      # @return [ApiConfiguration, nil] Global database configuration
-      attr_reader :global_config
-
-      # @return [Object] RubyLLM configuration object
-      attr_reader :ruby_llm_config
-
-      # Creates a new resolved configuration
-      #
-      # @param tenant_config [ApiConfiguration, nil] Tenant-specific config
-      # @param global_config [ApiConfiguration, nil] Global database config
-      # @param ruby_llm_config [Object] RubyLLM.configuration
-      def initialize(tenant_config:, global_config:, ruby_llm_config:)
-        @tenant_config = tenant_config
-        @global_config = global_config
-        @ruby_llm_config = ruby_llm_config
-        @resolved_cache = {}
-      end
-
-      # Resolves a specific attribute value using the priority chain
-      #
-      # @param attr_name [Symbol, String] The attribute name
-      # @return [Object, nil] The resolved value
-      def resolve(attr_name)
-        attr_sym = attr_name.to_sym
-        return @resolved_cache[attr_sym] if @resolved_cache.key?(attr_sym)
-
-        @resolved_cache[attr_sym] = resolve_attribute(attr_sym)
-      end
-
-      # Returns the source of a resolved attribute value
-      #
-      # @param attr_name [Symbol, String] The attribute name
-      # @return [String] Source label: "tenant:ID", "global_db", "ruby_llm_config", or "not_set"
-      def source_for(attr_name)
-        attr_sym = attr_name.to_sym
-
-        # Check tenant config first (if present and inherits or has value)
-        if tenant_config&.has_value?(attr_sym)
-          return "tenant:#{tenant_config.scope_id}"
-        end
-
-        # Check global DB config (only if tenant inherits or no tenant)
-        if should_check_global?(attr_sym) && global_config&.has_value?(attr_sym)
-          return "global_db"
-        end
-
-        # Check RubyLLM config
-        if ruby_llm_value_present?(attr_sym)
-          return "ruby_llm_config"
-        end
-
-        "not_set"
-      end
-
-      # Returns all resolved values as a hash
-      #
-      # @return [Hash] All resolved configuration values
-      def to_hash
-        self.class.resolvable_attributes.each_with_object({}) do |attr, hash|
-          value = resolve(attr)
-          hash[attr] = value if value.present?
-        end
-      end
-
-      # Returns a hash suitable for RubyLLM configuration
-      #
-      # Only includes values that differ from or override the current
-      # RubyLLM configuration.
-      #
-      # @return [Hash] Configuration hash for RubyLLM
-      def to_ruby_llm_options
-        to_hash.slice(*ruby_llm_configurable_attributes)
-      end
-
-      # Applies the resolved configuration to RubyLLM
-      #
-      # This temporarily overrides RubyLLM.configuration with the
-      # resolved values. Useful for per-request configuration.
-      #
-      # @return [void]
-      def apply_to_ruby_llm!
-        options = to_ruby_llm_options
-        return if options.empty?
-
-        RubyLLM.configure do |config|
-          options.each do |key, value|
-            setter = "#{key}="
-            config.public_send(setter, value) if config.respond_to?(setter)
-          end
-        end
-      end
-
-      # Dynamic accessor for resolvable attributes
-      # Uses method_missing to provide accessors without eager loading constants
-      #
-      # @param method_name [Symbol] The method being called
-      # @param args [Array] Method arguments
-      # @return [Object] The resolved value for the attribute
-      def method_missing(method_name, *args)
-        if self.class.resolvable_attributes.include?(method_name)
-          resolve(method_name)
-        else
-          super
-        end
-      end
-
-      # Indicates which dynamic methods are supported
-      #
-      # @param method_name [Symbol] The method name to check
-      # @param include_private [Boolean] Whether to include private methods
-      # @return [Boolean] True if the method is a resolvable attribute
-      def respond_to_missing?(method_name, include_private = false)
-        self.class.resolvable_attributes.include?(method_name) || super
-      end
-
-      # Returns provider status with source information
-      #
-      # @return [Array<Hash>] Provider status with source info
-      def provider_statuses_with_source
-        ApiConfiguration::PROVIDERS.map do |key, info|
-          key_attr = info[:key_attr]
-          value = resolve(key_attr)
-
-          {
-            key: key,
-            name: info[:name],
-            configured: value.present?,
-            masked_key: value.present? ? mask_string(value) : nil,
-            source: source_for(key_attr),
-            capabilities: info[:capabilities]
-          }
-        end
-      end
-
-      # Checks if any database configuration exists
-      #
-      # @return [Boolean]
-      def has_db_config?
-        tenant_config.present? || global_config.present?
-      end
-
-      # Returns summary of configuration sources
-      #
-      # @return [Hash] Summary with counts per source
-      def source_summary
-        summary = Hash.new(0)
-
-        self.class.resolvable_attributes.each do |attr|
-          source = source_for(attr)
-          summary[source] += 1 if resolve(attr).present?
-        end
-
-        summary
-      end
-
-      # Public method to get raw RubyLLM config value for an attribute
-      # This returns the value from RubyLLM.configuration (initializer/ENV)
-      # regardless of any database overrides.
-      #
-      # @param attr_name [Symbol, String] The attribute name
-      # @return [Object, nil] The RubyLLM config value
-      def ruby_llm_value_for(attr_name)
-        ruby_llm_value(attr_name.to_sym)
-      end
-
-      # Masks a string for display (public wrapper)
-      #
-      # @param value [String] The string to mask
-      # @return [String] Masked string
-      def mask_string(value)
-        return nil if value.blank?
-        return "****" if value.length <= 8
-
-        "#{value[0..1]}****#{value[-4..]}"
-      end
-
-      private
-
-      # Resolves a single attribute using the priority chain
-      #
-      # @param attr_sym [Symbol] The attribute name
-      # @return [Object, nil] The resolved value
-      def resolve_attribute(attr_sym)
-        # 1. Check tenant config
-        if tenant_config&.has_value?(attr_sym)
-          return tenant_config.send(attr_sym)
-        end
-
-        # 2. Check global DB config (if tenant allows inheritance or no tenant)
-        if should_check_global?(attr_sym)
-          if global_config&.has_value?(attr_sym)
-            return global_config.send(attr_sym)
-          end
-        end
-
-        # 3. Fall back to RubyLLM config
-        ruby_llm_value(attr_sym)
-      end
-
-      # Determines if we should check global config
-      #
-      # @param attr_sym [Symbol] The attribute name
-      # @return [Boolean]
-      def should_check_global?(attr_sym)
-        return true unless tenant_config
-
-        # If tenant has inherit_global_defaults enabled, check global
-        tenant_config.inherit_global_defaults != false
-      end
-
-      # Gets a value from RubyLLM configuration
-      #
-      # @param attr_sym [Symbol] The attribute name
-      # @return [Object, nil]
-      def ruby_llm_value(attr_sym)
-        return nil unless ruby_llm_config
-
-        # Map our attribute names to RubyLLM config method names
-        method_name = ruby_llm_config_mapping(attr_sym)
-        return nil unless method_name
-
-        if ruby_llm_config.respond_to?(method_name)
-          ruby_llm_config.send(method_name)
-        end
-      rescue StandardError
-        nil
-      end
-
-      # Checks if a RubyLLM config value is present
-      #
-      # @param attr_sym [Symbol] The attribute name
-      # @return [Boolean]
-      def ruby_llm_value_present?(attr_sym)
-        value = ruby_llm_value(attr_sym)
-        value.present?
-      end
-
-      # Maps our attribute names to RubyLLM configuration method names
-      #
-      # @param attr_sym [Symbol] Our attribute name
-      # @return [Symbol, nil] RubyLLM config method name
-      def ruby_llm_config_mapping(attr_sym)
-        # Most attributes map directly
-        mapping = {
-          openai_api_key: :openai_api_key,
-          anthropic_api_key: :anthropic_api_key,
-          gemini_api_key: :gemini_api_key,
-          deepseek_api_key: :deepseek_api_key,
-          mistral_api_key: :mistral_api_key,
-          perplexity_api_key: :perplexity_api_key,
-          openrouter_api_key: :openrouter_api_key,
-          gpustack_api_key: :gpustack_api_key,
-          xai_api_key: :xai_api_key,
-          ollama_api_key: :ollama_api_key,
-          bedrock_api_key: :bedrock_api_key,
-          bedrock_secret_key: :bedrock_secret_key,
-          bedrock_session_token: :bedrock_session_token,
-          bedrock_region: :bedrock_region,
-          vertexai_credentials: :vertexai_credentials,
-          vertexai_project_id: :vertexai_project_id,
-          vertexai_location: :vertexai_location,
-          openai_api_base: :openai_api_base,
-          gemini_api_base: :gemini_api_base,
-          ollama_api_base: :ollama_api_base,
-          gpustack_api_base: :gpustack_api_base,
-          xai_api_base: :xai_api_base,
-          openai_organization_id: :openai_organization_id,
-          openai_project_id: :openai_project_id,
-          default_model: :default_model,
-          default_embedding_model: :default_embedding_model,
-          default_image_model: :default_image_model,
-          default_moderation_model: :default_moderation_model,
-          request_timeout: :request_timeout,
-          max_retries: :max_retries,
-          retry_interval: :retry_interval,
-          retry_backoff_factor: :retry_backoff_factor,
-          retry_interval_randomness: :retry_interval_randomness,
-          http_proxy: :http_proxy
-        }
-
-        mapping[attr_sym]
-      end
-
-      # Returns attributes that can be set on RubyLLM configuration
-      #
-      # @return [Array<Symbol>]
-      def ruby_llm_configurable_attributes
-        ApiConfiguration::API_KEY_ATTRIBUTES +
-          ApiConfiguration::ENDPOINT_ATTRIBUTES +
-          ApiConfiguration::MODEL_ATTRIBUTES +
-          ApiConfiguration::CONNECTION_ATTRIBUTES +
-          %i[
-            openai_organization_id
-            openai_project_id
-            bedrock_region
-            vertexai_project_id
-            vertexai_location
-          ]
-      end
-
-    end
-  end
-end