decision_agent 0.3.0 → 1.1.0

data/lib/decision_agent/dsl/helpers/parameter_parsing_helpers.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Helpers
+      # Parameter parsing helpers for ConditionEvaluator
+      module ParameterParsingHelpers
+        def self.parse_range(value, param_cache:, param_cache_mutex:)
+          normalized = Operators::Base.normalize_params_to_hash(value, %i[min max])
+          cache_key = Operators::Base.normalize_param_cache_key(normalized, "range")
+
+          cached = param_cache[cache_key]
+          return cached if cached
+
+          param_cache_mutex.synchronize do
+            param_cache[cache_key] ||= parse_range_impl(normalized)
+          end
+        end
+
+        def self.parse_range_impl(value)
+          normalized = Operators::Base.normalize_params_to_hash(value, %i[min max])
+          return nil unless normalized.is_a?(Hash)
+
+          min = normalized[:min] || normalized["min"]
+          max = normalized[:max] || normalized["max"]
+          return nil unless min && max
+
+          { min: min, max: max }
+        end
+
+        def self.parse_modulo_params(value, param_cache:, param_cache_mutex:)
+          normalized = Operators::Base.normalize_params_to_hash(value, %i[divisor remainder])
+          cache_key = Operators::Base.normalize_param_cache_key(normalized, "modulo")
+
+          cached = param_cache[cache_key]
+          return cached if cached
+
+          param_cache_mutex.synchronize do
+            param_cache[cache_key] ||= parse_modulo_params_impl(normalized)
+          end
+        end
+
+        def self.parse_modulo_params_impl(value)
+          normalized = Operators::Base.normalize_params_to_hash(value, %i[divisor remainder])
+          return nil unless normalized.is_a?(Hash)
+
+          divisor = normalized[:divisor] || normalized["divisor"]
+          remainder = normalized[:remainder] || normalized["remainder"]
+          return nil unless divisor && !remainder.nil?
+
+          { divisor: divisor, remainder: remainder }
+        end
+
+        def self.parse_power_params(value)
+          normalized = Operators::Base.normalize_params_to_hash(value, %i[exponent result])
+          return nil unless normalized.is_a?(Hash)
+
+          exponent = normalized[:exponent] || normalized["exponent"]
+          result = normalized[:result] || normalized["result"]
+          return nil unless exponent && !result.nil?
+
+          { exponent: exponent, result: result }
+        end
+
+        def self.parse_atan2_params(value)
+          normalized = Operators::Base.normalize_params_to_hash(value, %i[y result])
+          return nil unless normalized.is_a?(Hash)
+
+          y = normalized[:y] || normalized["y"]
+          result = normalized[:result] || normalized["result"]
+          return nil unless y && !result.nil?
+
+          { y: y, result: result }
+        end
+
+        def self.parse_gcd_lcm_params(value)
+          normalized = Operators::Base.normalize_params_to_hash(value, %i[other result])
+          return nil unless normalized.is_a?(Hash)
+
+          other = normalized[:other] || normalized["other"]
+          result = normalized[:result] || normalized["result"]
+          return nil unless other && !result.nil?
+
+          { other: other, result: result }
+        end
+
+        def self.parse_percentile_params(value)
+          return nil unless value.is_a?(Hash)
+
+          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
+
+        def self.parse_duration_params(value)
+          return nil unless value.is_a?(Hash)
+
+          end_field = value["end"] || value[:end]
+          return nil unless end_field
+
+          {
+            end: end_field.to_s,
+            min: value["min"] || value[:min],
+            max: value["max"] || value[:max],
+            gt: value["gt"] || value[:gt],
+            lt: value["lt"] || value[:lt],
+            gte: value["gte"] || value[:gte],
+            lte: value["lte"] || value[:lte]
+          }
+        end
+
+        def self.parse_date_arithmetic_params(value, unit = :days)
+          return nil unless value.is_a?(Hash)
+
+          unit_value = value[unit.to_s] || value[unit]
+          return nil unless unit_value.is_a?(Numeric)
+
+          {
+            unit => unit_value.to_f,
+            target: value["target"] || value[:target] || "now",
+            compare: value["compare"] || value[:compare],
+            eq: value["eq"] || value[:eq],
+            gt: value["gt"] || value[:gt],
+            lt: value["lt"] || value[:lt],
+            gte: value["gte"] || value[:gte],
+            lte: value["lte"] || value[:lte]
+          }
+        end
+
+        def self.parse_moving_window_params(value)
+          return nil unless value.is_a?(Hash)
+
+          window = value["window"] || value[:window]
+          return nil unless window.is_a?(Numeric) && window.positive?
+
+          {
+            window: window.to_i,
+            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]
+          }
+        end
+
+        def self.parse_compound_interest_params(value)
+          return nil unless value.is_a?(Hash)
+
+          rate = value["rate"] || value[:rate]
+          periods = value["periods"] || value[:periods]
+          return nil unless rate.is_a?(Numeric) && periods.is_a?(Numeric) && periods.positive?
+
+          {
+            rate: rate.to_f,
+            periods: periods.to_f,
+            result: value["result"] || value[:result],
+            compare: value["compare"] || value[:compare],
+            threshold: value["threshold"] || value[:threshold]
+          }
+        end
+
+        def self.parse_present_value_params(value)
+          return nil unless value.is_a?(Hash)
+
+          rate = value["rate"] || value[:rate]
+          periods = value["periods"] || value[:periods]
+          return nil unless rate.is_a?(Numeric) && periods.is_a?(Numeric) && periods.positive?
+
+          {
+            rate: rate.to_f,
+            periods: periods.to_f,
+            result: value["result"] || value[:result]
+          }
+        end
+
+        def self.parse_future_value_params(value)
+          parse_present_value_params(value)
+        end
+
+        def self.parse_payment_params(value)
+          parse_compound_interest_params(value)
+        end
+
+        def self.parse_join_params(value)
+          return nil unless value.is_a?(Hash)
+
+          separator = value["separator"] || value[:separator] || ","
+          {
+            separator: separator.to_s,
+            result: value["result"] || value[:result],
+            contains: value["contains"] || value[:contains]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/dsl/helpers/template_helpers.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Helpers
+      # Template expansion and mapping helpers for ConditionEvaluator
+      module TemplateHelpers
+        def self.expand_template_params(params, context_hash, get_nested_value:)
+          return {} unless params.is_a?(Hash)
+
+          params.transform_values do |value|
+            expand_template_value(value, context_hash, get_nested_value: get_nested_value)
+          end
+        end
+
+        def self.expand_template_value(value, context_hash, get_nested_value:)
+          return value unless value.is_a?(String)
+          return value unless value.match?(/\{\{.*\}\}/)
+
+          # Extract path from {{path}} syntax
+          value.gsub(/\{\{([^}]+)\}\}/) do |_match|
+            path = Regexp.last_match(1).strip
+            get_nested_value.call(context_hash, path) || value
+          end
+        end
+
+        def self.apply_mapping(response_data, mapping, get_nested_value:)
+          return {} unless response_data.is_a?(Hash)
+          return {} unless mapping.is_a?(Hash)
+
+          mapping.each_with_object({}) do |(source_key, target_key), result|
+            source_value = get_nested_value.call(response_data, source_key.to_s)
+            result[target_key.to_s] = source_value unless source_value.nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/dsl/helpers/utility_helpers.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Helpers
+      # Utility helpers for ConditionEvaluator
+      module UtilityHelpers
+        def self.get_nested_value(hash, key_path, get_cached_path:)
+          keys = get_cached_path.call(key_path)
+          keys.reduce(hash) do |memo, key|
+            return nil unless memo.is_a?(Hash)
+
+            # OPTIMIZE: try symbol first (most common), then string
+            # Check key existence first to avoid double lookup
+            key_sym = key.to_sym
+            if memo.key?(key_sym)
+              memo[key_sym]
+            elsif memo.key?(key)
+              memo[key]
+            end
+          end
+        end
+
+        def self.comparable?(val1, val2)
+          # Both are numeric - allow comparison between different numeric types
+          # (e.g., Integer and Float are comparable in Ruby)
+          return true if val1.is_a?(Numeric) && val2.is_a?(Numeric)
+
+          # Both are strings - require exact same type
+          return val1.instance_of?(val2.class) if val1.is_a?(String) && val2.is_a?(String)
+
+          false
+        end
+
+        def self.epsilon_equal?(value1, value2, epsilon = 1e-10)
+          (value1 - value2).abs < epsilon
+        end
+
+        def self.string_operator?(actual_value, expected_value)
+          actual_value.is_a?(String) && expected_value.is_a?(String)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Operators
+      # Base utilities shared across all operator modules
+      module Base
+        # Normalize params to hash - converts arrays to hashes for better performance
+        # If value is an array and keys are provided, convert to hash
+        # If value is already a hash, normalize keys to symbols
+        def self.normalize_params_to_hash(value, keys)
+          if value.is_a?(Array) && value.size == keys.size
+            # Convert array to hash for better performance with large params
+            keys.each_with_index.with_object({}) do |(key, idx), hash|
+              hash[key] = value[idx]
+            end
+          elsif value.is_a?(Hash)
+            # Normalize hash keys to symbols for consistency
+            value.each_with_object({}) do |(k, v), h|
+              key = k.is_a?(String) ? k.to_sym : k
+              h[key] = v
+            end
+          else
+            value
+          end
+        end
+
+        # Normalize parameter value for cache key generation
+        def self.normalize_param_cache_key(value, prefix)
+          case value
+          when Array
+            "#{prefix}:#{value.inspect}"
+          when Hash
+            # Normalize keys to symbols and sort for consistent cache keys
+            normalized = value.each_with_object({}) do |(k, v), h|
+              key = k.is_a?(String) ? k.to_sym : k
+              h[key] = v
+            end
+            sorted_keys = normalized.keys.sort
+            "#{prefix}:#{sorted_keys.map { |k| "#{k}:#{normalized[k]}" }.join(',')}"
+          else
+            "#{prefix}:#{value.inspect}"
+          end
+        end
+
+        # Compare aggregation result with expected value (supports hash with comparison operators)
+        def self.compare_aggregation_result(actual, expected)
+          if expected.is_a?(Hash)
+            result = true
+            result &&= (actual >= expected[:min]) if expected[:min]
+            result &&= (actual <= expected[:max]) if expected[:max]
+            result &&= (actual > expected[:gt]) if expected[:gt]
+            result &&= (actual < expected[:lt]) if expected[:lt]
+            result &&= (actual >= expected[:gte]) if expected[:gte]
+            result &&= (actual <= expected[:lte]) if expected[:lte]
+            result &&= (actual == expected[:eq]) if expected[:eq]
+            result
+          else
+            actual == expected
+          end
+        end
+
+        # Epsilon comparison for floating point numbers
+        def self.epsilon_equal?(a, b, epsilon = 1e-10) # rubocop:disable Naming/MethodParameterName
+          (a - b).abs < epsilon
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Operators
+      # Handles basic comparison operators: eq, neq, gt, gte, lt, lte, in, present, blank
+      module BasicComparisonOperators
+        def self.handle(op, actual_value, expected_value)
+          case op
+          when "eq"
+            # Equality - uses Ruby's == for comparison
+            actual_value == expected_value
+
+          when "neq"
+            # Not equal - inverse of ==
+            actual_value != expected_value
+
+          when "gt"
+            # Greater than - only for comparable types (numbers, strings)
+            comparable?(actual_value, expected_value) && actual_value > expected_value
+
+          when "gte"
+            # Greater than or equal - only for comparable types
+            comparable?(actual_value, expected_value) && actual_value >= expected_value
+
+          when "lt"
+            # Less than - only for comparable types
+            comparable?(actual_value, expected_value) && actual_value < expected_value
+
+          when "lte"
+            # Less than or equal - only for comparable types
+            comparable?(actual_value, expected_value) && actual_value <= expected_value
+
+          when "in"
+            # Array membership - checks if actual_value is in the expected array
+            Array(expected_value).include?(actual_value)
+
+          when "present"
+            # PRESENT SEMANTICS:
+            # Returns true if value exists AND is not empty
+            # - nil: false
+            # - Empty string "": false
+            # - Empty array []: false
+            # - Empty hash {}: false
+            # - Zero 0: true (zero is a valid value)
+            # - False boolean: true (false is a valid value)
+            # - Non-empty values: true
+            !actual_value.nil? && (actual_value.respond_to?(:empty?) ? !actual_value.empty? : true)
+
+          when "blank"
+            # BLANK SEMANTICS:
+            # Returns true if value is nil OR empty
+            # - nil: true
+            # - Empty string "": true
+            # - Empty array []: true
+            # - Empty hash {}: true
+            # - Zero 0: false (zero is a valid value)
+            # - False boolean: false (false is a valid value)
+            # - Non-empty values: false
+            actual_value.nil? || (actual_value.respond_to?(:empty?) ? actual_value.empty? : false)
+          end
+          # Returns nil if not handled by this module
+        end
+
+        # Checks if two values can be compared with <, >, <=, >=
+        # Allows comparison between numeric types (Float, Integer, etc.) or same string types
+        def self.comparable?(val1, val2)
+          # Both are numeric - allow comparison between different numeric types
+          # (e.g., Integer and Float are comparable in Ruby)
+          return true if val1.is_a?(Numeric) && val2.is_a?(Numeric)
+
+          # Both are strings - require exact same type
+          return val1.instance_of?(val2.class) if val1.is_a?(String) && val2.is_a?(String)
+
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module Dsl
+    module Operators
+      # Handles collection operators: contains_all, contains_any, intersects, subset_of
+      module CollectionOperators
+        def self.handle(op, actual_value, expected_value)
+          case op
+          when "contains_all"
+            # Checks if array contains all specified elements
+            return false unless actual_value.is_a?(Array)
+            return false unless expected_value.is_a?(Array)
+            return true if expected_value.empty?
+
+            # OPTIMIZE: Use Set for O(1) lookups instead of O(n) include?
+            actual_set = actual_value.to_set
+            expected_value.all? { |item| actual_set.include?(item) }
+
+          when "contains_any"
+            # Checks if array contains any of the specified elements
+            return false unless actual_value.is_a?(Array)
+            return false unless expected_value.is_a?(Array)
+            return false if expected_value.empty?
+
+            # OPTIMIZE: Use Set for O(1) lookups instead of O(n) include?
+            actual_set = actual_value.to_set
+            expected_value.any? { |item| actual_set.include?(item) }
+
+          when "intersects"
+            # Checks if two arrays have any common elements
+            return false unless actual_value.is_a?(Array)
+            return false unless expected_value.is_a?(Array)
+            return false if actual_value.empty? || expected_value.empty?
+
+            # OPTIMIZE: Use Set intersection for O(n) instead of array & which creates intermediate array
+            if actual_value.size <= expected_value.size
+              expected_set = expected_value.to_set
+              actual_value.any? { |item| expected_set.include?(item) }
+            else
+              actual_set = actual_value.to_set
+              expected_value.any? { |item| actual_set.include?(item) }
+            end
+
+          when "subset_of"
+            # Checks if array is a subset of another array
+            return false unless actual_value.is_a?(Array)
+            return false unless expected_value.is_a?(Array)
+            return true if actual_value.empty?
+
+            # OPTIMIZE: Use Set for O(1) lookups instead of O(n) include?
+            expected_set = expected_value.to_set
+            actual_value.all? { |item| expected_set.include?(item) }
+          end
+          # Returns nil if not handled by this module
+        end
+      end
+    end
+  end
+end