decision_agent 0.3.0 → 1.0.1

data/lib/decision_agent/dsl/schema_validator.rb

@@ -20,6 +20,7 @@ module DecisionAgent
         join length
         contains_all contains_any intersects subset_of
         within_radius in_polygon
+        fetch_from_api
       ].freeze
 
       CONDITION_TYPES = %w[all any field].freeze
@@ -162,9 +163,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 +178,24 @@ module DecisionAgent
         end
 
         validate_operator(operator, path)
+        validate_field_condition_value(operator, value, path)
+        validate_fetch_from_api_value(value, path) if (operator.to_s == "fetch_from_api") && value
+        validate_field_path(field, path) if field
+      end
 
-        # 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
+      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)
 
-        # Validate dot-notation in field path
-        validate_field_path(field, path) if field
+        nil
+      end
+
+      def validate_field_condition_value(operator, value, path)
+        # Validate value (not required for 'present', 'blank', and 'fetch_from_api' has special validation)
+        return if %w[present blank fetch_from_api].include?(operator.to_s)
+        return unless value.nil?
+
+        @errors << "#{path}: Field condition missing 'value' key for operator '#{operator}'"
       end
 
       def validate_operator(operator, path)
@@ -253,13 +265,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 +286,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)
@@ -276,6 +296,24 @@ module DecisionAgent
         @errors << "#{rule_path}.then.reason: Must be a string, got #{reason.class}"
       end
 
+      def validate_fetch_from_api_value(value, path)
+        unless value.is_a?(Hash)
+          @errors << "#{path}: 'fetch_from_api' operator requires 'value' to be a hash with 'endpoint', 'params', and optional 'mapping'"
+          return
+        end
+
+        endpoint = value["endpoint"] || value[:endpoint]
+        @errors << "#{path}: 'fetch_from_api' operator requires 'endpoint' in value hash" unless endpoint
+
+        params = value["params"] || value[:params]
+        @errors << "#{path}: 'fetch_from_api' operator 'params' must be a hash if provided" unless params.nil? || params.is_a?(Hash)
+
+        mapping = value["mapping"] || value[:mapping]
+        return if mapping.nil? || mapping.is_a?(Hash)
+
+        @errors << "#{path}: 'fetch_from_api' operator 'mapping' must be a hash if provided"
+      end
+
       def format_errors
         header = "Rule DSL validation failed with #{@errors.size} error#{'s' if @errors.size > 1}:\n\n"
         numbered_errors = @errors.map.with_index { |err, idx| "  #{idx + 1}. #{err}" }.join("\n")

data/lib/decision_agent/evaluators/dmn_evaluator.rb

@@ -39,9 +39,12 @@ module DecisionAgent
       def evaluate(context, feedback: {})
         hit_policy = @decision.decision_table.hit_policy
 
+        # Collect explainability traces
+        explainability_result = collect_explainability(context, hit_policy)
+
         # Short-circuit for FIRST and PRIORITY policies
         if %w[FIRST PRIORITY].include?(hit_policy)
-          first_match = find_first_matching_evaluation(context, feedback: feedback)
+          first_match = find_first_matching_evaluation(context, explainability_result: explainability_result)
           return first_match if first_match
 
           # If no match found, return nil (consistent with apply_first_policy behavior)
@@ -49,10 +52,25 @@ module DecisionAgent
         end
 
         # For UNIQUE, ANY, COLLECT - need all matches
-        matching_evaluations = find_all_matching_evaluations(context, feedback: feedback)
+        matching_evaluations = find_all_matching_evaluations(context, explainability_result: explainability_result)
 
         # Apply hit policy to select the appropriate evaluation
-        apply_hit_policy(matching_evaluations)
+        result = apply_hit_policy(matching_evaluations)
+
+        # Add explainability to metadata by creating new Evaluation with updated metadata
+        if result && explainability_result
+          metadata = result.metadata.dup
+          metadata[:explainability] = explainability_result.to_h
+          result = Evaluation.new(
+            decision: result.decision,
+            weight: result.weight,
+            reason: result.reason,
+            evaluator_name: result.evaluator_name,
+            metadata: metadata
+          )
+        end
+
+        result
       end
 
       private
@@ -61,8 +79,51 @@ module DecisionAgent
         @name
       end
 
+      # Collect explainability traces for DMN evaluation
+      def collect_explainability(context, hit_policy)
+        ctx = context.is_a?(Context) ? context : Context.new(context)
+        rules = @rules_json["rules"] || []
+        rule_traces = []
+
+        rules.each do |rule|
+          rule_id = rule["id"] || "rule_#{rules.index(rule)}"
+          if_clause = rule["if"]
+          next unless if_clause
+
+          # Create trace collector for this rule
+          trace_collector = Explainability::TraceCollector.new
+
+          # Evaluate condition with tracing
+          matched = Dsl::ConditionEvaluator.evaluate(
+            if_clause,
+            ctx,
+            trace_collector: trace_collector
+          )
+
+          then_clause = rule["then"] || {}
+          rule_trace = Explainability::RuleTrace.new(
+            rule_id: rule_id,
+            matched: matched,
+            condition_traces: trace_collector.traces,
+            decision: then_clause["decision"],
+            weight: then_clause["weight"],
+            reason: then_clause["reason"]
+          )
+
+          rule_traces << rule_trace
+
+          # Stop after first match for FIRST/PRIORITY policies (short-circuit evaluation)
+          break if matched && %w[FIRST PRIORITY].include?(hit_policy)
+        end
+
+        Explainability::ExplainabilityResult.new(
+          evaluator_name: @name,
+          rule_traces: rule_traces
+        )
+      end
+
       # Find first matching rule (for short-circuiting)
-      def find_first_matching_evaluation(context, feedback: {})
+      def find_first_matching_evaluation(context, explainability_result: nil, feedback: {})
         ctx = context.is_a?(Context) ? context : Context.new(context)
         rules = @rules_json["rules"] || []
 
@@ -70,20 +131,33 @@ module DecisionAgent
           if_clause = rule["if"]
           next unless if_clause
 
-          next unless Dsl::ConditionEvaluator.evaluate(if_clause, ctx)
+          # If explainability is already collected, use the trace data
+          matched = if explainability_result
+                      rule_trace = explainability_result.rule_traces.find { |rt| rt.rule_id == (rule["id"] || "rule_#{rules.index(rule)}") }
+                      rule_trace&.matched
+                    else
+                      Dsl::ConditionEvaluator.evaluate(if_clause, ctx)
+                    end
+
+          next unless matched
 
           then_clause = rule["then"]
+          metadata = {
+            type: "dmn_rule",
+            rule_id: rule["id"],
+            ruleset: @rules_json["ruleset"],
+            hit_policy: @decision.decision_table.hit_policy
+          }
+
+          # Add explainability data to metadata
+          metadata[:explainability] = explainability_result.to_h if explainability_result
+
           return Evaluation.new(
             decision: then_clause["decision"],
             weight: then_clause["weight"] || 1.0,
             reason: then_clause["reason"] || "Rule matched",
             evaluator_name: @name,
-            metadata: {
-              type: "dmn_rule",
-              rule_id: rule["id"],
-              ruleset: @rules_json["ruleset"],
-              hit_policy: @decision.decision_table.hit_policy
-            }
+            metadata: metadata
           )
         end
 
@@ -91,7 +165,7 @@ module DecisionAgent
       end
 
       # Find all matching rules (not just first)
-      def find_all_matching_evaluations(context, feedback: {})
+      def find_all_matching_evaluations(context, explainability_result: nil, feedback: {})
         ctx = context.is_a?(Context) ? context : Context.new(context)
         rules = @rules_json["rules"] || []
         matching = []
@@ -100,20 +174,33 @@ module DecisionAgent
           if_clause = rule["if"]
           next unless if_clause
 
-          next unless Dsl::ConditionEvaluator.evaluate(if_clause, ctx)
+          # If explainability is already collected, use the trace data
+          matched = if explainability_result
+                      rule_trace = explainability_result.rule_traces.find { |rt| rt.rule_id == (rule["id"] || "rule_#{rules.index(rule)}") }
+                      rule_trace&.matched
+                    else
+                      Dsl::ConditionEvaluator.evaluate(if_clause, ctx)
+                    end
+
+          next unless matched
 
           then_clause = rule["then"]
+          metadata = {
+            type: "dmn_rule",
+            rule_id: rule["id"],
+            ruleset: @rules_json["ruleset"],
+            hit_policy: @decision.decision_table.hit_policy
+          }
+
+          # Add explainability data to metadata (will be added to final result)
+          # For now, we'll add it to the final result after hit policy is applied
+
           matching << Evaluation.new(
             decision: then_clause["decision"],
             weight: then_clause["weight"] || 1.0,
             reason: then_clause["reason"] || "Rule matched",
             evaluator_name: @name,
-            metadata: {
-              type: "dmn_rule",
-              rule_id: rule["id"],
-              ruleset: @rules_json["ruleset"],
-              hit_policy: @decision.decision_table.hit_policy
-            }
+            metadata: metadata
           )
         end
 

data/lib/decision_agent/evaluators/json_rule_evaluator.rb

@@ -19,37 +19,97 @@ module DecisionAgent
       end
 
       def evaluate(context, feedback: {})
-        ctx = context.is_a?(Context) ? context : Context.new(context)
+        ctx = context.is_a?(DecisionAgent::Context) ? context : DecisionAgent::Context.new(context)
 
-        matched_rule = find_first_matching_rule(ctx)
+        # Collect explainability traces (this also finds the matching rule)
+        explainability_result = collect_explainability(ctx)
 
+        # Find the matched rule from explainability result
+        matched_rule_trace = explainability_result&.matched_rules&.first
+        return nil unless matched_rule_trace
+
+        # Find the original rule to get the then clause
+        rules = @ruleset["rules"] || []
+        matched_rule = rules.find { |r| (r["id"] || "rule_#{rules.index(r)}") == matched_rule_trace.rule_id }
         return nil unless matched_rule
 
         then_clause = matched_rule["then"]
 
+        metadata = {
+          type: "json_rule",
+          rule_id: matched_rule["id"],
+          ruleset: @ruleset_name
+        }
+
+        # Add explainability data to metadata
+        metadata[:explainability] = explainability_result.to_h if explainability_result
+
         Evaluation.new(
           decision: then_clause["decision"],
           weight: then_clause["weight"] || 1.0,
           reason: then_clause["reason"] || "Rule matched",
           evaluator_name: @name,
-          metadata: {
-            type: "json_rule",
-            rule_id: matched_rule["id"],
-            ruleset: @ruleset_name
-          }
+          metadata: metadata
         )
       end
 
       private
 
-      def find_first_matching_rule(context)
+      def collect_explainability(context)
+        rules = @ruleset["rules"] || []
+        rule_traces = []
+
+        rules.each do |rule|
+          rule_id = rule["id"] || "rule_#{rules.index(rule)}"
+          if_clause = rule["if"]
+          next unless if_clause
+
+          # Create trace collector for this rule
+          trace_collector = Explainability::TraceCollector.new
+
+          # Evaluate condition with tracing
+          matched = Dsl::ConditionEvaluator.evaluate(
+            if_clause,
+            context,
+            trace_collector: trace_collector
+          )
+
+          then_clause = rule["then"] || {}
+          rule_trace = Explainability::RuleTrace.new(
+            rule_id: rule_id,
+            matched: matched,
+            condition_traces: trace_collector.traces,
+            decision: then_clause["decision"],
+            weight: then_clause["weight"],
+            reason: then_clause["reason"]
+          )
+
+          rule_traces << rule_trace
+
+          # Stop after first match (short-circuit evaluation)
+          break if matched
+        end
+
+        Explainability::ExplainabilityResult.new(
+          evaluator_name: @name,
+          rule_traces: rule_traces
+        )
+      end
+
+      def find_first_matching_rule(context, explainability_result = nil)
         rules = @ruleset["rules"] || []
 
         rules.find do |rule|
           if_clause = rule["if"]
           next false unless if_clause
 
-          Dsl::ConditionEvaluator.evaluate(if_clause, context)
+          # If explainability is already collected, use the trace data
+          if explainability_result
+            rule_trace = explainability_result.rule_traces.find { |rt| rt.rule_id == (rule["id"] || "rule_#{rules.index(rule)}") }
+            rule_trace&.matched
+          else
+            Dsl::ConditionEvaluator.evaluate(if_clause, context)
+          end
         end
       end
 

data/lib/decision_agent/explainability/condition_trace.rb

@@ -0,0 +1,83 @@
+module DecisionAgent
+  module Explainability
+    # Represents a single condition evaluation with its result and values
+    class ConditionTrace
+      attr_reader :field, :operator, :expected_value, :actual_value, :result, :description
+
+      def initialize(field:, operator:, expected_value:, actual_value:, result:, description: nil)
+        @field = field.to_s.freeze
+        @operator = operator.to_s.freeze
+        @expected_value = expected_value
+        @actual_value = actual_value
+        @result = result
+        @description = description ? description.to_s.freeze : generate_description
+        freeze
+      end
+
+      def passed?
+        @result == true
+      end
+
+      def failed?
+        @result == false
+      end
+
+      def to_s
+        @description
+      end
+
+      def to_h
+        {
+          field: @field,
+          operator: @operator,
+          expected_value: @expected_value,
+          actual_value: @actual_value,
+          result: @result,
+          description: @description
+        }
+      end
+
+      private
+
+      def generate_description
+        case @operator
+        when "eq"
+          "#{@field} = #{format_value(@actual_value)}"
+        when "neq"
+          "#{@field} != #{format_value(@expected_value)}"
+        when "gt"
+          "#{@field} > #{format_value(@expected_value)}"
+        when "gte"
+          "#{@field} >= #{format_value(@expected_value)}"
+        when "lt"
+          "#{@field} < #{format_value(@expected_value)}"
+        when "lte"
+          "#{@field} <= #{format_value(@expected_value)}"
+        when "in"
+          "#{@field} in #{format_value(@expected_value)}"
+        when "contains"
+          "#{@field} contains #{format_value(@expected_value)}"
+        when "present"
+          "#{@field} is present"
+        when "blank"
+          "#{@field} is blank"
+        else
+          "#{@field} #{@operator} #{format_value(@expected_value)}"
+        end
+      end
+
+      def format_value(value)
+        case value
+        when String
+          value.inspect
+        when Array, Hash
+          value.inspect
+        when Time, Date, DateTime
+          value.to_s
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/explainability/explainability_result.rb

@@ -0,0 +1,52 @@
+module DecisionAgent
+  module Explainability
+    # Container for all explainability data from a decision evaluation
+    class ExplainabilityResult
+      attr_reader :rule_traces, :evaluator_name
+
+      def initialize(evaluator_name:, rule_traces: [])
+        @evaluator_name = evaluator_name.to_s.freeze
+        @rule_traces = Array(rule_traces).freeze
+        freeze
+      end
+
+      def matched_rules
+        @rule_traces.select(&:matched)
+      end
+
+      def evaluated_rules
+        @rule_traces
+      end
+
+      def all_passed_conditions
+        @rule_traces.flat_map(&:passed_conditions)
+      end
+
+      def all_failed_conditions
+        @rule_traces.flat_map(&:failed_conditions)
+      end
+
+      def because(verbose: false) # rubocop:disable Lint/UnusedMethodArgument
+        # verbose parameter kept for API compatibility, but currently both modes return same format
+        all_passed_conditions.map(&:description)
+      end
+
+      def failed_conditions(verbose: false)
+        if verbose
+          all_failed_conditions.map(&:to_h)
+        else
+          all_failed_conditions.map(&:description)
+        end
+      end
+
+      def to_h(verbose: false)
+        {
+          evaluator_name: @evaluator_name,
+          rule_traces: @rule_traces.map(&:to_h), # Always include full rule traces for reconstruction
+          because: because(verbose: verbose),
+          failed_conditions: failed_conditions(verbose: verbose)
+        }
+      end
+    end
+  end
+end

data/lib/decision_agent/explainability/rule_trace.rb

@@ -0,0 +1,39 @@
+module DecisionAgent
+  module Explainability
+    # Represents the trace of a rule evaluation including all conditions
+    class RuleTrace
+      attr_reader :rule_id, :matched, :condition_traces, :decision, :weight, :reason
+
+      def initialize(rule_id:, matched:, condition_traces: [], decision: nil, weight: nil, reason: nil)
+        @rule_id = rule_id.to_s.freeze
+        @matched = matched
+        @condition_traces = Array(condition_traces).freeze
+        @decision = decision ? decision.to_s.freeze : nil
+        @weight = weight
+        @reason = reason ? reason.to_s.freeze : nil
+        freeze
+      end
+
+      def passed_conditions
+        @condition_traces.select(&:passed?)
+      end
+
+      def failed_conditions
+        @condition_traces.select(&:failed?)
+      end
+
+      def to_h
+        {
+          rule_id: @rule_id,
+          matched: @matched,
+          decision: @decision,
+          weight: @weight,
+          reason: @reason,
+          condition_traces: @condition_traces.map(&:to_h),
+          passed_conditions: passed_conditions.map(&:description),
+          failed_conditions: failed_conditions.map(&:description)
+        }
+      end
+    end
+  end
+end

data/lib/decision_agent/explainability/trace_collector.rb

@@ -0,0 +1,24 @@
+module DecisionAgent
+  module Explainability
+    # Collects condition traces during evaluation
+    class TraceCollector
+      attr_reader :traces
+
+      def initialize
+        @traces = []
+      end
+
+      def add_trace(trace)
+        @traces << trace
+      end
+
+      def clear
+        @traces.clear
+      end
+
+      def empty?
+        @traces.empty?
+      end
+    end
+  end
+end

data/lib/decision_agent/monitoring/alert_manager.rb

@@ -16,6 +16,7 @@ module DecisionAgent
         @alert_handlers = []
         @check_interval = 60 # seconds
         @monitoring_thread = nil
+        @rule_counter = 0
         freeze_config
       end
 
@@ -198,7 +199,10 @@ module DecisionAgent
       end
 
       def generate_rule_id(name)
-        "#{sanitize_name(name)}_#{Time.now.to_i}_#{rand(1000)}"
+        synchronize do
+          @rule_counter += 1
+          "#{sanitize_name(name)}_#{Time.now.to_i}_#{@rule_counter}"
+        end
       end
 
       def sanitize_name(name)

data/lib/decision_agent/simulation/errors.rb

@@ -0,0 +1,18 @@
+module DecisionAgent
+  module Simulation
+    # Base error class for simulation module
+    class SimulationError < StandardError; end
+
+    # Error raised when scenario execution fails
+    class ScenarioExecutionError < SimulationError; end
+
+    # Error raised when historical data is invalid
+    class InvalidHistoricalDataError < SimulationError; end
+
+    # Error raised when version comparison fails
+    class VersionComparisonError < SimulationError; end
+
+    # Error raised when shadow test configuration is invalid
+    class InvalidShadowTestError < SimulationError; end
+  end
+end