decision_agent 0.3.0 → 1.1.0

data/lib/decision_agent/evaluators/dmn_evaluator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../dmn/adapter"
 require_relative "../dmn/errors"
 require_relative "base"
@@ -39,9 +41,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 +54,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 +81,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 +133,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 +167,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 +176,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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 
 module DecisionAgent
@@ -19,38 +21,81 @@ 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)
+
+        # Collect explainability traces (this also finds the matching rule)
+        explainability_result = collect_explainability(ctx)
 
-        matched_rule = find_first_matching_rule(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.find do |rule|
+        rules.each do |rule|
+          rule_id = rule["id"] || "rule_#{rules.index(rule)}"
           if_clause = rule["if"]
-          next false unless if_clause
+          next unless if_clause
+
+          # Create trace collector for this rule
+          trace_collector = Explainability::TraceCollector.new
 
-          Dsl::ConditionEvaluator.evaluate(if_clause, context)
+          # 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
 
       # Deep freeze helper method

data/lib/decision_agent/evaluators/static_evaluator.rb

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

data/lib/decision_agent/explainability/condition_trace.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+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,50 @@
+# frozen_string_literal: true
+
+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 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,41 @@
+# frozen_string_literal: true
+
+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,26 @@
+# frozen_string_literal: true
+
+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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "monitor"
 
 module DecisionAgent
@@ -16,6 +18,7 @@ module DecisionAgent
         @alert_handlers = []
         @check_interval = 60 # seconds
         @monitoring_thread = nil
+        @rule_counter = 0
         freeze_config
       end
 
@@ -176,21 +179,6 @@ module DecisionAgent
         end
       end
 
-      def self.decision_anomaly(expected_rate: 100, variance: 0.3)
-        lambda do |stats|
-          total = stats.dig(:decisions, :total) || 0
-          time_range = stats.dig(:summary, :time_range)
-
-          # Simple anomaly detection based on rate
-          return false unless time_range
-
-          lower_bound = expected_rate * (1 - variance)
-          upper_bound = expected_rate * (1 + variance)
-
-          total < lower_bound || total > upper_bound
-        end
-      end
-
       private
 
       def freeze_config
@@ -198,7 +186,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)