ruby_llm-agents 1.3.3 → 2.0.0

data/lib/ruby_llm/agents/image/generator/content_policy.rb

@@ -1,95 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class ImageGenerator
-      # Content policy enforcement for image generation prompts
-      #
-      # Validates prompts against configurable policy levels to prevent
-      # generation of inappropriate content.
-      #
-      # @example Using content policy in a generator
-      #   class SafeImageGenerator < RubyLLM::Agents::ImageGenerator
-      #     content_policy :strict
-      #   end
-      #
-      # @example Manual validation
-      #   ContentPolicy.validate!("A beautiful sunset", :moderate)
-      #   # => nil (passes)
-      #
-      #   ContentPolicy.validate!("Violent scene", :strict)
-      #   # => raises ContentPolicyViolation
-      #
-      module ContentPolicy
-        # Blocked patterns by policy level
-        #
-        # :strict   - Blocks violence, nudity, hate, weapons, drugs
-        # :moderate - Blocks explicit content, gore, hate speech
-        # :standard - No blocking (relies on model's built-in filters)
-        # :none     - No validation at all
-        #
-        BLOCKED_PATTERNS = {
-          strict: [
-            /\b(violence|violent|gore|blood|death|kill|murder)\b/i,
-            /\b(nude|naked|nsfw|explicit|sexual|porn)\b/i,
-            /\b(hate|racist|discrimination|slur)\b/i,
-            /\b(weapon|gun|knife|bomb|explosive)\b/i,
-            /\b(drug|cocaine|heroin|meth)\b/i
-          ],
-          moderate: [
-            /\b(nude|naked|nsfw|explicit|sexual|porn)\b/i,
-            /\b(gore|graphic.?violence)\b/i,
-            /\b(hate.?speech|slur)\b/i
-          ],
-          standard: [],
-          none: []
-        }.freeze
-
-        class << self
-          # Validate a prompt against a policy level
-          #
-          # @param prompt [String] The prompt to validate
-          # @param level [Symbol] Policy level (:none, :standard, :moderate, :strict)
-          # @raise [ContentPolicyViolation] If prompt violates the policy
-          def validate!(prompt, level)
-            return if level == :none || level.nil?
-
-            patterns = BLOCKED_PATTERNS[level.to_sym] || BLOCKED_PATTERNS[:standard]
-
-            patterns.each do |pattern|
-              if prompt.match?(pattern)
-                raise ContentPolicyViolation,
-                      "Prompt contains content blocked by #{level} policy"
-              end
-            end
-          end
-
-          # Check if a prompt passes the policy (non-raising version)
-          #
-          # @param prompt [String] The prompt to check
-          # @param level [Symbol] Policy level
-          # @return [Boolean] true if prompt passes
-          def valid?(prompt, level)
-            validate!(prompt, level)
-            true
-          rescue ContentPolicyViolation
-            false
-          end
-
-          # Get the matched pattern for a violation (for debugging)
-          #
-          # @param prompt [String] The prompt to check
-          # @param level [Symbol] Policy level
-          # @return [Regexp, nil] The matched pattern or nil
-          def matched_pattern(prompt, level)
-            patterns = BLOCKED_PATTERNS[level.to_sym] || []
-            patterns.find { |pattern| prompt.match?(pattern) }
-          end
-        end
-      end
-
-      # Exception raised when a prompt violates content policy
-      class ContentPolicyViolation < StandardError; end
-    end
-  end
-end

data/lib/ruby_llm/agents/infrastructure/redactor.rb

@@ -1,130 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    # Unified redaction utility for PII and sensitive data
-    #
-    # Provides methods to redact sensitive information from hashes, arrays, and strings
-    # based on configurable field names and regex patterns.
-    #
-    # @example Redacting a hash
-    #   Redactor.redact({ password: "secret", name: "John" })
-    #   # => { password: "[REDACTED]", name: "John" }
-    #
-    # @example Redacting a string with patterns
-    #   Redactor.redact_string("SSN: 123-45-6789")
-    #   # => "SSN: [REDACTED]"
-    #
-    # @see RubyLLM::Agents::Configuration
-    # @api public
-    module Redactor
-      class << self
-        # Redacts sensitive data from an object (hash, array, or primitive)
-        #
-        # @param obj [Object] The object to redact
-        # @param config [Configuration, nil] Optional configuration override
-        # @return [Object] The redacted object (new object, original not modified)
-        def redact(obj, config = nil)
-          config ||= RubyLLM::Agents.configuration
-
-          case obj
-          when Hash
-            redact_hash(obj, config)
-          when Array
-            redact_array(obj, config)
-          when String
-            redact_string(obj, config)
-          else
-            obj
-          end
-        end
-
-        # Redacts sensitive data from a string using configured patterns
-        #
-        # @param str [String, nil] The string to redact
-        # @param config [Configuration, nil] Optional configuration override
-        # @return [String, nil] The redacted string
-        def redact_string(str, config = nil)
-          return nil if str.nil?
-          return str unless str.is_a?(String)
-
-          config ||= RubyLLM::Agents.configuration
-          result = str.dup
-
-          # Apply pattern-based redaction
-          config.redaction_patterns.each do |pattern|
-            result = result.gsub(pattern, config.redaction_placeholder)
-          end
-
-          # Truncate if max length is configured
-          max_length = config.redaction_max_value_length
-          if max_length && result.length > max_length
-            result = result[0, max_length] + "..."
-          end
-
-          result
-        end
-
-        private
-
-        # Redacts sensitive fields from a hash
-        #
-        # @param hash [Hash] The hash to redact
-        # @param config [Configuration] The configuration
-        # @return [Hash] The redacted hash
-        def redact_hash(hash, config)
-          hash.each_with_object({}) do |(key, value), result|
-            key_str = key.to_s.downcase
-
-            if sensitive_field?(key_str, config)
-              result[key] = config.redaction_placeholder
-            else
-              result[key] = redact_value(value, config)
-            end
-          end
-        end
-
-        # Redacts sensitive values from an array
-        #
-        # @param array [Array] The array to redact
-        # @param config [Configuration] The configuration
-        # @return [Array] The redacted array
-        def redact_array(array, config)
-          array.map { |item| redact(item, config) }
-        end
-
-        # Redacts a single value based on its type
-        #
-        # @param value [Object] The value to redact
-        # @param config [Configuration] The configuration
-        # @return [Object] The redacted value
-        def redact_value(value, config)
-          case value
-          when Hash
-            redact_hash(value, config)
-          when Array
-            redact_array(value, config)
-          when String
-            redact_string(value, config)
-          when defined?(ActiveRecord::Base) && ActiveRecord::Base
-            # Convert ActiveRecord objects to safe references
-            { id: value&.id, type: value&.class&.name }
-          else
-            value
-          end
-        end
-
-        # Checks if a field name is sensitive
-        #
-        # @param field_name [String] The field name to check (lowercase)
-        # @param config [Configuration] The configuration
-        # @return [Boolean] true if the field should be redacted
-        def sensitive_field?(field_name, config)
-          config.redaction_fields.any? do |sensitive|
-            field_name.include?(sensitive.downcase)
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,158 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    # Wrapper for moderation results with threshold and category filtering
-    #
-    # Provides a filtered view of moderation results based on configured
-    # thresholds and category filters. The raw result is still accessible
-    # for full details.
-    #
-    # @example Basic usage
-    #   result = ModerationResult.new(
-    #     result: raw_moderation,
-    #     threshold: 0.8,
-    #     categories: [:hate, :violence]
-    #   )
-    #
-    #   result.flagged?  # Only true if score >= 0.8 AND category is hate or violence
-    #   result.passed?   # Opposite of flagged?
-    #
-    # @api public
-    class ModerationResult
-      # @return [Object] The raw moderation result from RubyLLM
-      attr_reader :raw_result
-
-      # @return [Float, nil] Configured threshold for flagging
-      attr_reader :threshold
-
-      # @return [Array<Symbol>, nil] Categories to filter on
-      attr_reader :filter_categories
-
-      # Creates a new ModerationResult
-      #
-      # @param result [Object] Raw moderation result from RubyLLM
-      # @param threshold [Float, nil] Score threshold (0.0-1.0)
-      # @param categories [Array<Symbol>, nil] Categories to check
-      def initialize(result:, threshold: nil, categories: nil)
-        @raw_result = result
-        @threshold = threshold
-        @filter_categories = categories&.map(&:to_sym)
-      end
-
-      # Returns whether the content should be flagged
-      #
-      # Considers both threshold and category filters if configured.
-      # Content is flagged only if:
-      # - Raw result is flagged AND
-      # - Score meets threshold (if configured) AND
-      # - Category matches filter (if configured)
-      #
-      # @return [Boolean] true if content should be flagged
-      def flagged?
-        return false unless raw_result.flagged?
-
-        passes_threshold? && passes_category_filter?
-      end
-
-      # Returns whether the content passed moderation
-      #
-      # @return [Boolean] true if content is not flagged
-      def passed?
-        !flagged?
-      end
-
-      # Returns the flagged categories, filtered by configuration
-      #
-      # @return [Array<String, Symbol>] Categories that triggered flagging
-      def flagged_categories
-        cats = raw_result.flagged_categories || []
-        return cats unless filter_categories&.any?
-
-        cats.select { |c| filter_categories.include?(normalize_category(c)) }
-      end
-
-      # Returns all category scores from the raw result
-      #
-      # @return [Hash{String, Symbol => Float}] Category to score mapping
-      def category_scores
-        raw_result.category_scores || {}
-      end
-
-      # Returns the moderation result ID
-      #
-      # @return [String, nil] Result identifier
-      def id
-        raw_result.id
-      end
-
-      # Returns the model used for moderation
-      #
-      # @return [String, nil] Model identifier
-      def model
-        raw_result.model
-      end
-
-      # Returns the maximum score across all categories
-      #
-      # @return [Float] Highest category score
-      def max_score
-        scores = category_scores.values
-        scores.any? ? scores.max : 0.0
-      end
-
-      # Returns whether the raw result was flagged (ignoring filters)
-      #
-      # @return [Boolean] true if raw result was flagged
-      def raw_flagged?
-        raw_result.flagged?
-      end
-
-      # Converts the result to a hash
-      #
-      # @return [Hash] Result data as a hash
-      def to_h
-        {
-          flagged: flagged?,
-          raw_flagged: raw_flagged?,
-          flagged_categories: flagged_categories,
-          category_scores: category_scores,
-          max_score: max_score,
-          threshold: threshold,
-          filter_categories: filter_categories,
-          model: model,
-          id: id
-        }
-      end
-
-      private
-
-      # Checks if the max score meets the threshold
-      #
-      # @return [Boolean] true if threshold is met or not configured
-      def passes_threshold?
-        return true unless threshold
-
-        max_score >= threshold
-      end
-
-      # Checks if any flagged categories match the filter
-      #
-      # @return [Boolean] true if categories match or no filter configured
-      def passes_category_filter?
-        return true unless filter_categories&.any?
-
-        normalized_flagged = (raw_result.flagged_categories || []).map { |c| normalize_category(c) }
-        (normalized_flagged & filter_categories).any?
-      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
-    end
-  end
-end

data/lib/ruby_llm/agents/text/moderator.rb

@@ -1,237 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../results/moderation_result"
-
-module RubyLLM
-  module Agents
-    # Standalone moderator for content moderation using the middleware pipeline
-    #
-    # Provides a class-based interface for moderating content with built-in
-    # support for caching, instrumentation, and multi-tenancy through the
-    # middleware pipeline.
-    #
-    # @example Basic usage
-    #   class ContentModerator < RubyLLM::Agents::Moderator
-    #     model 'omni-moderation-latest'
-    #   end
-    #
-    #   result = ContentModerator.call(text: "content to check")
-    #   result.flagged?  # => true/false
-    #
-    # @example With configuration
-    #   class StrictModerator < RubyLLM::Agents::Moderator
-    #     model 'omni-moderation-latest'
-    #     threshold 0.7
-    #     categories :hate, :violence, :harassment
-    #   end
-    #
-    # @example Runtime override
-    #   result = ContentModerator.call(
-    #     text: "content",
-    #     threshold: 0.9,
-    #     categories: [:hate]
-    #   )
-    #
-    # @api public
-    class Moderator < BaseAgent
-      class << self
-        # Returns the agent type for moderators
-        #
-        # @return [Symbol] :moderation
-        def agent_type
-          :moderation
-        end
-
-        # @!group Moderation-specific DSL
-
-        # Sets or returns the moderation model
-        #
-        # Defaults to the moderation model from configuration, not the
-        # conversation model that BaseAgent uses.
-        #
-        # @param value [String, nil] Model identifier to set
-        # @return [String] Current model setting
-        def model(value = nil)
-          @model = value if value
-          return @model if defined?(@model) && @model
-
-          # For inheritance: check if parent is also a Moderator
-          if superclass.respond_to?(:agent_type) && superclass.agent_type == :moderation
-            superclass.model
-          else
-            default_moderation_model
-          end
-        end
-
-        # Sets or returns the score threshold
-        #
-        # @param value [Float, nil] Threshold value (0.0-1.0)
-        # @return [Float, nil] Current threshold
-        def threshold(value = nil)
-          @threshold = value if value
-          @threshold || inherited_or_default(:threshold, nil)
-        end
-
-        # Sets or returns the categories to check
-        #
-        # @param cats [Array<Symbol>] Category symbols
-        # @return [Array<Symbol>, nil] Current categories
-        def categories(*cats)
-          @categories = cats.flatten.map(&:to_sym) if cats.any?
-          @categories || inherited_or_default(:categories, nil)
-        end
-
-        # @!endgroup
-
-        # Factory method to instantiate and execute moderation
-        #
-        # @param text [String] Text to moderate
-        # @param options [Hash] Runtime options
-        # @option options [String] :model Override moderation model
-        # @option options [Float] :threshold Override threshold
-        # @option options [Array<Symbol>] :categories Override categories
-        # @option options [Object] :tenant Tenant for multi-tenancy
-        # @return [ModerationResult] The moderation result
-        def call(text:, **options)
-          new(text: text, **options).call
-        end
-
-        private
-
-        def inherited_or_default(method, default)
-          superclass.respond_to?(method) ? superclass.send(method) : default
-        end
-
-        def default_moderation_model
-          RubyLLM::Agents.configuration.default_moderation_model
-        rescue StandardError
-          "omni-moderation-latest"
-        end
-      end
-
-      # @!attribute [r] text
-      #   @return [String] Text to moderate
-      attr_reader :text
-
-      # Creates a new Moderator instance
-      #
-      # @param text [String] Text to moderate
-      # @param options [Hash] Runtime options
-      def initialize(text:, **options)
-        @text = text
-        @runtime_threshold = options.delete(:threshold)
-        @runtime_categories = options.delete(:categories)
-
-        # Set model to moderation model if not specified
-        options[:model] ||= self.class.model
-
-        super(**options)
-      end
-
-      # Executes the moderation through the middleware pipeline
-      #
-      # @return [ModerationResult] The moderation result
-      def call
-        context = build_context
-        result_context = Pipeline::Executor.execute(context)
-        result_context.output
-      end
-
-      # The input for this moderation operation
-      #
-      # Used by the pipeline to generate cache keys and for instrumentation.
-      #
-      # @return [String] The text being moderated
-      def user_prompt
-        text
-      end
-
-      # Core moderation execution
-      #
-      # This is called by the Pipeline::Executor after middleware
-      # has been applied. Only contains the moderation API logic.
-      #
-      # @param context [Pipeline::Context] The execution context
-      # @return [void] Sets context.output with the ModerationResult
-      def execute(context)
-        # Track timing internally
-        execution_started_at = Time.current
-
-        moderation_opts = {}
-        moderation_opts[:model] = resolved_model if resolved_model
-
-        raw_result = RubyLLM.moderate(text, **moderation_opts)
-
-        execution_completed_at = Time.current
-        duration_ms = ((execution_completed_at - execution_started_at) * 1000).to_i
-
-        # Update context with basic info (no tokens for moderation)
-        context.input_tokens = 0
-        context.output_tokens = 0
-        context.total_cost = 0.0
-
-        # Build final result
-        context.output = ModerationResult.new(
-          result: raw_result,
-          threshold: resolved_threshold,
-          categories: resolved_categories
-        )
-      end
-
-      # Generates the cache key for this moderation
-      #
-      # @return [String] Cache key in format "ruby_llm_agents/moderation/..."
-      def agent_cache_key
-        components = [
-          "ruby_llm_agents",
-          "moderation",
-          self.class.name,
-          self.class.version,
-          resolved_model,
-          resolved_threshold,
-          resolved_categories&.sort&.join(","),
-          Digest::SHA256.hexdigest(text)
-        ].compact
-
-        components.join("/")
-      end
-
-      private
-
-      # Builds context for pipeline execution
-      #
-      # @return [Pipeline::Context] The context object
-      def build_context
-        Pipeline::Context.new(
-          input: user_prompt,
-          agent_class: self.class,
-          agent_instance: self,
-          model: resolved_model,
-          tenant: @options[:tenant],
-          skip_cache: @options[:skip_cache]
-        )
-      end
-
-      # Resolves the model to use
-      #
-      # @return [String] The model identifier
-      def resolved_model
-        @model || self.class.model
-      end
-
-      # Resolves the threshold to use
-      #
-      # @return [Float, nil] The threshold
-      def resolved_threshold
-        @runtime_threshold || self.class.threshold
-      end
-
-      # Resolves the categories to check
-      #
-      # @return [Array<Symbol>, nil] The categories
-      def resolved_categories
-        @runtime_categories || self.class.categories
-      end
-    end
-  end
-end