decision_agent 0.2.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,12 +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)
 
-        @errors << "#{rule_path}.then: Missing required field 'decision'" unless 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)
@@ -266,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)
@@ -275,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

@@ -0,0 +1,308 @@
+require_relative "../dmn/adapter"
+require_relative "../dmn/errors"
+require_relative "base"
+require_relative "json_rule_evaluator"
+
+module DecisionAgent
+  module Evaluators
+    # Evaluates DMN decision models
+    class DmnEvaluator < Base
+      attr_reader :model, :decision_id
+
+      def initialize(model:, decision_id:, name: nil)
+        @model = model
+        @decision_id = decision_id.to_s
+        @name = name || "DmnEvaluator(#{@decision_id})"
+
+        # Find and validate decision
+        @decision = @model.find_decision(@decision_id)
+        raise Dmn::InvalidDmnModelError, "Decision '#{@decision_id}' not found" unless @decision
+        raise Dmn::InvalidDmnModelError, "Decision '#{@decision_id}' has no decision table" unless @decision.decision_table
+
+        # Convert to JSON rules for execution
+        adapter = Dmn::Adapter.new(@decision.decision_table)
+        @rules_json = adapter.to_json_rules
+
+        # Create internal JSON rule evaluator
+        @json_evaluator = JsonRuleEvaluator.new(
+          rules_json: @rules_json,
+          name: @name
+        )
+
+        # Freeze for thread safety
+        @model.freeze
+        @decision_id.freeze
+        @name.freeze
+        freeze
+      end
+
+      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, explainability_result: explainability_result)
+          return first_match if first_match
+
+          # If no match found, return nil (consistent with apply_first_policy behavior)
+          return nil
+        end
+
+        # For UNIQUE, ANY, COLLECT - need all matches
+        matching_evaluations = find_all_matching_evaluations(context, explainability_result: explainability_result)
+
+        # Apply hit policy to select the appropriate evaluation
+        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
+
+      def evaluator_name
+        @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, explainability_result: nil, feedback: {})
+        ctx = context.is_a?(Context) ? context : Context.new(context)
+        rules = @rules_json["rules"] || []
+
+        rules.each do |rule|
+          if_clause = rule["if"]
+          next unless if_clause
+
+          # 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: metadata
+          )
+        end
+
+        nil
+      end
+
+      # Find all matching rules (not just first)
+      def find_all_matching_evaluations(context, explainability_result: nil, feedback: {})
+        ctx = context.is_a?(Context) ? context : Context.new(context)
+        rules = @rules_json["rules"] || []
+        matching = []
+
+        rules.each do |rule|
+          if_clause = rule["if"]
+          next unless if_clause
+
+          # 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: metadata
+          )
+        end
+
+        matching
+      end
+
+      # Apply hit policy to matching evaluations
+      def apply_hit_policy(matching_evaluations)
+        hit_policy = @decision.decision_table.hit_policy
+
+        case hit_policy
+        when "UNIQUE"
+          apply_unique_policy(matching_evaluations)
+        when "FIRST"
+          apply_first_policy(matching_evaluations)
+        when "PRIORITY"
+          apply_priority_policy(matching_evaluations)
+        when "ANY"
+          apply_any_policy(matching_evaluations)
+        when "COLLECT"
+          apply_collect_policy(matching_evaluations)
+        else
+          # Default to FIRST if unknown policy
+          apply_first_policy(matching_evaluations)
+        end
+      end
+
+      # UNIQUE: Exactly one rule must match
+      def apply_unique_policy(matching_evaluations)
+        case matching_evaluations.size
+        when 0
+          raise Dmn::InvalidDmnModelError,
+                "UNIQUE hit policy requires exactly one matching rule, but none matched"
+        when 1
+          matching_evaluations.first
+        else
+          rule_ids = matching_evaluations.map { |e| e.metadata[:rule_id] }.join(", ")
+          raise Dmn::InvalidDmnModelError,
+                "UNIQUE hit policy requires exactly one matching rule, but #{matching_evaluations.size} matched: #{rule_ids}"
+        end
+      end
+
+      # FIRST: Return first matching rule (already in order)
+      def apply_first_policy(matching_evaluations)
+        return nil if matching_evaluations.empty?
+
+        matching_evaluations.first
+      end
+
+      # PRIORITY: Return rule with highest priority
+      # For now, we use rule order as priority (first rule = highest priority)
+      # In full DMN spec, outputs can have priority values defined
+      def apply_priority_policy(matching_evaluations)
+        return nil if matching_evaluations.empty?
+
+        # For now, return first match (rules are already in priority order)
+        # Future enhancement: check output priority values if defined
+        matching_evaluations.first
+      end
+
+      # ANY: All matching rules must have same output
+      def apply_any_policy(matching_evaluations)
+        return nil if matching_evaluations.empty?
+
+        # Check that all decisions are the same
+        first_decision = matching_evaluations.first.decision
+        all_same = matching_evaluations.all? { |e| e.decision == first_decision }
+
+        unless all_same
+          decisions = matching_evaluations.map(&:decision).uniq.join(", ")
+          rule_ids = matching_evaluations.map { |e| e.metadata[:rule_id] }.join(", ")
+          raise Dmn::InvalidDmnModelError,
+                "ANY hit policy requires all matching rules to have the same output, " \
+                "but found different outputs: #{decisions} (rules: #{rule_ids})"
+        end
+
+        matching_evaluations.first
+      end
+
+      # COLLECT: Return all matching rules
+      # Since Evaluation expects a single decision, we'll return the first one
+      # but include metadata about all matches
+      def apply_collect_policy(matching_evaluations)
+        return nil if matching_evaluations.empty?
+
+        # Return first evaluation but include all matches in metadata
+        first = matching_evaluations.first
+        all_decisions = matching_evaluations.map(&:decision)
+        all_rule_ids = matching_evaluations.map { |e| e.metadata[:rule_id] }
+
+        Evaluation.new(
+          decision: first.decision,
+          weight: first.weight,
+          reason: "COLLECT: #{matching_evaluations.size} rules matched",
+          evaluator_name: @name,
+          metadata: first.metadata.merge(
+            collect_count: matching_evaluations.size,
+            collect_decisions: all_decisions,
+            collect_rule_ids: all_rule_ids
+          )
+        )
+      end
+    end
+  end
+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