decision_agent 0.3.0 → 1.1.0

data/lib/decision_agent/dsl/operators/statistical_aggregations.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Operators
+      # Handles statistical aggregation operators: min, max, sum, average, median, stddev, variance, percentile, count
+      module StatisticalAggregations
+        def self.handle(op, actual_value, expected_value, param_cache: nil, param_cache_mutex: nil)
+          case op
+          when "min"
+            # Checks if min(field_value) equals expected_value
+            return false unless actual_value.is_a?(Array)
+            return false if actual_value.empty?
+            return false unless expected_value.is_a?(Numeric)
+
+            actual_value.min == expected_value
+
+          when "max"
+            # Checks if max(field_value) equals expected_value
+            return false unless actual_value.is_a?(Array)
+            return false if actual_value.empty?
+            return false unless expected_value.is_a?(Numeric)
+
+            actual_value.max == expected_value
+
+          when "sum"
+            # Checks if sum of numeric array equals expected_value
+            return false unless actual_value.is_a?(Array)
+            return false if actual_value.empty?
+
+            # OPTIMIZE: calculate sum in single pass, filtering as we go
+            sum_value = 0.0
+            found_numeric = false
+            actual_value.each do |v|
+              if v.is_a?(Numeric)
+                sum_value += v
+                found_numeric = true
+              end
+            end
+            return false unless found_numeric
+
+            Base.compare_aggregation_result(sum_value, expected_value)
+
+          when "average", "mean"
+            # Checks if average of numeric array equals expected_value
+            return false unless actual_value.is_a?(Array)
+            return false if actual_value.empty?
+
+            # OPTIMIZE: calculate sum and count in single pass
+            sum_value = 0.0
+            count = 0
+            actual_value.each do |v|
+              if v.is_a?(Numeric)
+                sum_value += v
+                count += 1
+              end
+            end
+            return false if count.zero?
+
+            avg_value = sum_value / count
+            Base.compare_aggregation_result(avg_value, expected_value)
+
+          when "median"
+            # Checks if median of numeric array equals expected_value
+            return false unless actual_value.is_a?(Array)
+            return false if actual_value.empty?
+
+            numeric_array = actual_value.select { |v| v.is_a?(Numeric) }.sort
+            return false if numeric_array.empty?
+
+            median_value = if numeric_array.size.odd?
+                             numeric_array[numeric_array.size / 2]
+                           else
+                             (numeric_array[(numeric_array.size / 2) - 1] + numeric_array[numeric_array.size / 2]) / 2.0
+                           end
+            Base.compare_aggregation_result(median_value, expected_value)
+
+          when "stddev", "standard_deviation"
+            # Checks if standard deviation of numeric array equals expected_value
+            return false unless actual_value.is_a?(Array)
+            return false if actual_value.size < 2
+
+            numeric_array = actual_value.select { |v| v.is_a?(Numeric) }
+            return false if numeric_array.size < 2
+
+            mean = numeric_array.sum.to_f / numeric_array.size
+            variance = numeric_array.sum { |v| (v - mean)**2 } / numeric_array.size
+            stddev_value = Math.sqrt(variance)
+            Base.compare_aggregation_result(stddev_value, expected_value)
+
+          when "variance"
+            # Checks if variance of numeric array equals expected_value
+            return false unless actual_value.is_a?(Array)
+            return false if actual_value.size < 2
+
+            numeric_array = actual_value.select { |v| v.is_a?(Numeric) }
+            return false if numeric_array.size < 2
+
+            mean = numeric_array.sum.to_f / numeric_array.size
+            variance_value = numeric_array.sum { |v| (v - mean)**2 } / numeric_array.size
+            Base.compare_aggregation_result(variance_value, expected_value)
+
+          when "percentile"
+            # Checks if Nth percentile of numeric array meets threshold
+            return false unless actual_value.is_a?(Array)
+            return false if actual_value.empty?
+
+            numeric_array = actual_value.select { |v| v.is_a?(Numeric) }.sort
+            return false if numeric_array.empty?
+
+            params = parse_percentile_params(expected_value, param_cache: param_cache, param_cache_mutex: param_cache_mutex)
+            return false unless params
+
+            percentile_index = (params[:percentile] / 100.0) * (numeric_array.size - 1)
+            percentile_value = if percentile_index == percentile_index.to_i
+                                 numeric_array[percentile_index.to_i]
+                               else
+                                 lower = numeric_array[percentile_index.floor]
+                                 upper = numeric_array[percentile_index.ceil]
+                                 lower + ((upper - lower) * (percentile_index - percentile_index.floor))
+                               end
+
+            compare_percentile_result(percentile_value, params)
+
+          when "count"
+            # Checks if count of array elements meets threshold
+            return false unless actual_value.is_a?(Array)
+
+            count_value = actual_value.size
+            Base.compare_aggregation_result(count_value, expected_value)
+          end
+          # Returns nil if not handled by this module
+        end
+
+        # Parse percentile parameters
+        def self.parse_percentile_params(value, param_cache: nil, param_cache_mutex: nil)
+          return nil unless value.is_a?(Hash)
+
+          # Normalize to hash (already a hash, but normalize keys)
+          normalized = Base.normalize_params_to_hash(value, [])
+
+          cache = param_cache
+          mutex = param_cache_mutex
+          if cache.nil? || mutex.nil?
+            cache = ConditionEvaluator.instance_variable_get(:@param_cache)
+            mutex = ConditionEvaluator.instance_variable_get(:@param_cache_mutex)
+          end
+
+          cache_key = Base.normalize_param_cache_key(normalized, "percentile")
+          cached = cache[cache_key]
+          return cached if cached
+
+          mutex.synchronize do
+            cache[cache_key] ||= parse_percentile_params_impl(normalized)
+          end
+        end
+
+        def self.parse_percentile_params_impl(value)
+          percentile = value[:percentile] || value["percentile"]
+          return nil unless percentile.is_a?(Numeric) && percentile >= 0 && percentile <= 100
+
+          {
+            percentile: percentile.to_f,
+            threshold: value[:threshold] || value["threshold"],
+            gt: value[:gt] || value["gt"],
+            lt: value[:lt] || value["lt"],
+            gte: value[:gte] || value["gte"],
+            lte: value[:lte] || value["lte"],
+            eq: value[:eq] || value["eq"]
+          }
+        end
+
+        # Compare percentile result
+        def self.compare_percentile_result(actual, params)
+          result = true
+          result &&= (actual >= params[:threshold]) if params[:threshold]
+          result &&= (actual > params[:gt]) if params[:gt]
+          result &&= (actual < params[:lt]) if params[:lt]
+          result &&= (actual >= params[:gte]) if params[:gte]
+          result &&= (actual <= params[:lte]) if params[:lte]
+          result &&= (actual == params[:eq]) if params[:eq]
+          result
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/dsl/operators/string_aggregations.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Operators
+      # Handles string aggregation operators: join, length
+      module StringAggregations
+        def self.handle(op, actual_value, expected_value, param_cache: nil, param_cache_mutex: nil)
+          case op
+          when "join"
+            # Joins array of strings with separator
+            return false unless actual_value.is_a?(Array)
+            return false if actual_value.empty?
+
+            string_array = actual_value.map(&:to_s)
+            params = parse_join_params(expected_value, param_cache: param_cache, param_cache_mutex: param_cache_mutex)
+            return false unless params
+
+            joined = string_array.join(params[:separator])
+
+            if params[:result]
+              joined == params[:result]
+            elsif params[:contains]
+              joined.include?(params[:contains])
+            else
+              false
+            end
+
+          when "length"
+            # Gets length of string or array
+            return false if actual_value.nil?
+
+            length_value = if actual_value.is_a?(String) || actual_value.is_a?(Array)
+                             actual_value.length
+                           else
+                             return false
+                           end
+
+            compare_length_result(length_value, expected_value)
+          end
+          # Returns nil if not handled by this module
+        end
+
+        # Parse join parameters
+        def self.parse_join_params(value, param_cache: nil, param_cache_mutex: nil)
+          return nil unless value.is_a?(Hash)
+
+          normalized = Base.normalize_params_to_hash(value, [])
+
+          cache = param_cache
+          mutex = param_cache_mutex
+          if cache.nil? || mutex.nil?
+            cache = ConditionEvaluator.instance_variable_get(:@param_cache)
+            mutex = ConditionEvaluator.instance_variable_get(:@param_cache_mutex)
+          end
+
+          cache_key = Base.normalize_param_cache_key(normalized, "join")
+          cached = cache[cache_key]
+          return cached if cached
+
+          mutex.synchronize do
+            cache[cache_key] ||= parse_join_params_impl(normalized)
+          end
+        end
+
+        def self.parse_join_params_impl(value)
+          separator = value[:separator] || value["separator"]
+          return nil unless separator
+
+          {
+            separator: separator.to_s,
+            result: value[:result] || value["result"],
+            contains: value[:contains] || value["contains"]
+          }
+        end
+
+        # Compare length result
+        def self.compare_length_result(actual, expected)
+          ConditionEvaluator.compare_length_result(actual, expected)
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/dsl/operators/string_operators.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Operators
+      # Handles string operators: contains, starts_with, ends_with, matches
+      module StringOperators
+        def self.handle(op, actual_value, expected_value, regex_cache: nil, regex_cache_mutex: nil)
+          case op
+          when "contains"
+            # Checks if string contains substring (case-sensitive)
+            string_operator?(actual_value, expected_value) &&
+              actual_value.include?(expected_value)
+
+          when "starts_with"
+            # Checks if string starts with prefix (case-sensitive)
+            string_operator?(actual_value, expected_value) &&
+              actual_value.start_with?(expected_value)
+
+          when "ends_with"
+            # Checks if string ends with suffix (case-sensitive)
+            string_operator?(actual_value, expected_value) &&
+              actual_value.end_with?(expected_value)
+
+          when "matches"
+            # Matches string against regular expression
+            # expected_value can be a string (converted to regex) or Regexp object
+            if !actual_value.is_a?(String) || expected_value.nil?
+              false
+            else
+              begin
+                regex = get_cached_regex(expected_value, regex_cache: regex_cache, regex_cache_mutex: regex_cache_mutex)
+                !regex.match(actual_value).nil?
+              rescue RegexpError
+                false
+              end
+            end
+          end
+          # Returns nil if not handled by this module
+        end
+
+        # String operator validation
+        def self.string_operator?(actual_value, expected_value)
+          actual_value.is_a?(String) && expected_value.is_a?(String)
+        end
+
+        # Get or compile regex with caching
+        def self.get_cached_regex(pattern, regex_cache: nil, regex_cache_mutex: nil)
+          return pattern if pattern.is_a?(Regexp)
+
+          # Use provided caches or access ConditionEvaluator class variables
+          cache = regex_cache
+          mutex = regex_cache_mutex
+
+          if cache.nil? || mutex.nil?
+            cache = ConditionEvaluator.instance_variable_get(:@regex_cache)
+            mutex = ConditionEvaluator.instance_variable_get(:@regex_cache_mutex)
+          end
+
+          # Fast path: check cache without lock
+          cached = cache[pattern]
+          return cached if cached
+
+          # Slow path: compile and cache
+          mutex.synchronize do
+            cache[pattern] ||= Regexp.new(pattern.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/dsl/operators/time_component_operators.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Operators
+      # Handles time component extraction operators: hour_of_day, day_of_month, month, year, week_of_year
+      module TimeComponentOperators
+        def self.handle(op, actual_value, expected_value)
+          case op
+          when "hour_of_day"
+            # Extracts hour of day (0-23) and compares
+            return false unless actual_value
+
+            date = ConditionEvaluator.parse_date(actual_value)
+            return false unless date
+
+            hour = date.hour
+            compare_numeric_result(hour, expected_value)
+
+          when "day_of_month"
+            # Extracts day of month (1-31) and compares
+            return false unless actual_value
+
+            date = ConditionEvaluator.parse_date(actual_value)
+            return false unless date
+
+            day = date.day
+            compare_numeric_result(day, expected_value)
+
+          when "month"
+            # Extracts month (1-12) and compares
+            return false unless actual_value
+
+            date = ConditionEvaluator.parse_date(actual_value)
+            return false unless date
+
+            month = date.month
+            compare_numeric_result(month, expected_value)
+
+          when "year"
+            # Extracts year and compares
+            return false unless actual_value
+
+            date = ConditionEvaluator.parse_date(actual_value)
+            return false unless date
+
+            year = date.year
+            compare_numeric_result(year, expected_value)
+
+          when "week_of_year"
+            # Extracts week of year (1-52) and compares
+            return false unless actual_value
+
+            date = ConditionEvaluator.parse_date(actual_value)
+            return false unless date
+
+            week = date.strftime("%U").to_i + 1 # %U returns 0-53, we want 1-53
+            compare_numeric_result(week, expected_value)
+          end
+          # Returns nil if not handled by this module
+        end
+
+        # Compare numeric result (for time component extraction)
+        def self.compare_numeric_result(actual, expected)
+          return actual == expected unless expected.is_a?(Hash)
+
+          Helpers::ComparisonHelpers.compare_numeric_with_hash(actual, expected)
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/dsl/rule_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 
 module DecisionAgent

data/lib/decision_agent/dsl/schema_validator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Dsl
     # JSON Schema validator for Decision Agent rule DSL
@@ -7,8 +9,11 @@ module DecisionAgent
         eq neq gt gte lt lte in present blank
         contains starts_with ends_with matches
         between modulo
-        sin cos tan sqrt power exp log
-        round floor ceil abs
+        sin cos tan asin acos atan atan2
+        sinh cosh tanh
+        sqrt cbrt power exp log log10 log2
+        round floor ceil truncate abs
+        factorial gcd lcm
         min max sum average mean median stddev standard_deviation variance percentile count
         before_date after_date within_days day_of_week
         duration_seconds duration_minutes duration_hours duration_days
@@ -162,9 +167,10 @@ module DecisionAgent
       end
 
       def validate_field_condition(condition, path)
-        field = condition["field"] || condition[:field]
-        operator = condition["op"] || condition[:op]
-        value = condition["value"] || condition[:value]
+        # Use key? to properly handle false values (|| would treat false as falsy)
+        field = extract_key_value(condition, "field", :field)
+        operator = extract_key_value(condition, "op", :op)
+        value = extract_key_value(condition, "value", :value)
 
         # Validate field
         @errors << "#{path}: Field condition missing 'field' key" unless field
@@ -176,14 +182,23 @@ module DecisionAgent
         end
 
         validate_operator(operator, path)
+        validate_field_condition_value(operator, value, path)
+        validate_field_path(field, path) if field
+      end
+
+      def extract_key_value(hash, string_key, symbol_key)
+        return hash[string_key] if hash.key?(string_key)
+        return hash[symbol_key] if hash.key?(symbol_key)
+
+        nil
+      end
 
+      def validate_field_condition_value(operator, value, path)
         # Validate value (not required for 'present' and 'blank')
-        if !%w[present blank].include?(operator.to_s) && value.nil?
-          @errors << "#{path}: Field condition missing 'value' key for operator '#{operator}'"
-        end
+        return if %w[present blank].include?(operator.to_s)
+        return unless value.nil?
 
-        # Validate dot-notation in field path
-        validate_field_path(field, path) if field
+        @errors << "#{path}: Field condition missing 'value' key for operator '#{operator}'"
       end
 
       def validate_operator(operator, path)
@@ -253,13 +268,20 @@ module DecisionAgent
           return
         end
 
-        # Validate decision
-        decision = then_clause["decision"] || then_clause[:decision]
+        validate_then_clause_decision(then_clause, rule_path)
+        validate_then_clause_weight(then_clause, rule_path)
+        validate_then_clause_reason(then_clause, rule_path)
+      end
+
+      def validate_then_clause_decision(then_clause, rule_path)
+        # Use key? to properly handle false values (|| would treat false as falsy)
+        decision = extract_key_value(then_clause, "decision", :decision)
 
         # Check if decision exists (including false and 0, but not nil)
         @errors << "#{rule_path}.then: Missing required field 'decision'" if decision.nil?
+      end
 
-        # Validate optional weight
+      def validate_then_clause_weight(then_clause, rule_path)
         weight = then_clause["weight"] || then_clause[:weight]
 
         if weight && !weight.is_a?(Numeric)
@@ -267,8 +289,9 @@ module DecisionAgent
         elsif weight && (weight < 0.0 || weight > 1.0)
           @errors << "#{rule_path}.then.weight: Must be between 0.0 and 1.0, got #{weight}"
         end
+      end
 
-        # Validate optional reason
+      def validate_then_clause_reason(then_clause, rule_path)
         reason = then_clause["reason"] || then_clause[:reason]
 
         return unless reason && !reason.is_a?(String)

data/lib/decision_agent/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   class Error < StandardError; end
 

data/lib/decision_agent/evaluation.rb

@@ -1,7 +1,16 @@
+# frozen_string_literal: true
+
 module DecisionAgent
+  # Single evaluation produced by an evaluator: a suggested decision, weight, reason, and optional metadata.
   class Evaluation
     attr_reader :decision, :weight, :reason, :evaluator_name, :metadata
 
+    # @param decision [String, #to_s] The suggested decision value
+    # @param weight [Numeric] Importance of this evaluation (0.0 to 1.0)
+    # @param reason [String, #to_s] Human-readable reason for the decision
+    # @param evaluator_name [String, #to_s] Name of the evaluator that produced this
+    # @param metadata [Hash] Optional extra data (e.g. explainability)
+    # @raise [InvalidWeightError] when weight is not between 0.0 and 1.0
     def initialize(decision:, weight:, reason:, evaluator_name:, metadata: {})
       validate_weight!(weight)
 
@@ -14,6 +23,7 @@ module DecisionAgent
       freeze
     end
 
+    # @return [Hash] Symbol-keyed hash of decision, weight, reason, evaluator_name, metadata
     def to_h
       {
         decision: @decision,
@@ -24,6 +34,8 @@ module DecisionAgent
       }
     end
 
+    # @param other [Object] Object to compare
+    # @return [Boolean] true if other is an Evaluation with same attributes
     def ==(other)
       other.is_a?(Evaluation) &&
         @decision == other.decision &&
@@ -36,8 +48,8 @@ module DecisionAgent
     private
 
     def validate_weight!(weight)
-      w = weight.to_f
-      raise InvalidWeightError, weight unless w.between?(0.0, 1.0)
+      weight_value = weight.to_f
+      raise InvalidWeightError, weight unless weight_value.between?(0.0, 1.0)
     end
 
     def deep_freeze(obj)

data/lib/decision_agent/evaluators/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Evaluators
     class Base