decision_agent 0.3.0 → 1.1.0

data/lib/decision_agent/auth/session.rb

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

data/lib/decision_agent/auth/session_manager.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     class SessionManager

data/lib/decision_agent/auth/user.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bcrypt"
 require "securerandom"
 

data/lib/decision_agent/context.rb

@@ -1,25 +1,39 @@
+# frozen_string_literal: true
+
 module DecisionAgent
+  # Immutable, thread-safe wrapper around input data passed to evaluators.
+  # Data is deep-copied and deep-frozen on construction.
   class Context
     attr_reader :data
 
+    # @param data [Hash, Object] Input data; non-Hash is treated as empty Hash
     def initialize(data)
       # Create a deep copy before freezing to avoid mutating the original
+      # This is necessary for thread-safety even if it adds some overhead
       data_hash = data.is_a?(Hash) ? data : {}
       @data = deep_freeze(deep_dup(data_hash))
     end
 
+    # @param key [Object] Key to look up
+    # @return [Object, nil] Value for key, or nil if missing
     def [](key)
       @data[key]
     end
 
+    # @param key [Object] Key to look up
+    # @param default [Object] Value returned when key is missing (default: nil)
+    # @return [Object] Value for key, or default
     def fetch(key, default = nil)
       @data.fetch(key, default)
     end
 
+    # @param key [Object] Key to check
+    # @return [Boolean] Whether the key exists
     def key?(key)
       @data.key?(key)
     end
 
+    # @return [Hash] The underlying frozen data hash
     def to_h
       @data
     end

data/lib/decision_agent/decision.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 module DecisionAgent
+  # Result of {Agent#decide}: the chosen decision, confidence, explanations, and audit data.
   class Decision
     attr_reader :decision, :confidence, :explanations, :evaluations, :audit_payload
 
@@ -14,16 +17,122 @@ module DecisionAgent
       freeze
     end
 
-    def to_h
+    # Returns array of condition descriptions that led to this decision
+    # @param verbose [Boolean] If true, returns detailed condition information
+    # @return [Array<String>] Array of condition descriptions
+    def because(verbose: false)
+      all_explainability_results.flat_map { |er| er.because(verbose: verbose) }
+    end
+
+    # Returns array of condition descriptions that failed
+    # @param verbose [Boolean] If true, returns detailed condition information
+    # @return [Array<String>] Array of failed condition descriptions
+    def failed_conditions(verbose: false)
+      all_explainability_results.flat_map { |er| er.failed_conditions(verbose: verbose) }
+    end
+
+    # Returns explainability data in machine-readable format
+    # @param verbose [Boolean] If true, returns detailed explainability information
+    # @return [Hash] Explainability data
+    def explainability(verbose: false)
       {
         decision: @decision,
+        because: because(verbose: verbose),
+        failed_conditions: failed_conditions(verbose: verbose),
+        rule_traces: verbose ? all_explainability_results.map { |er| er.to_h(verbose: true) } : nil
+      }.compact
+    end
+
+    # Returns the decision as a hash (explainability-shaped plus confidence, evaluations, audit).
+    #
+    # @return [Hash] Symbol-keyed hash with :decision, :because, :failed_conditions, :confidence,
+    #   :explanations, :evaluations, :audit_payload, :explainability
+    def to_h
+      # Structure decision result as explainability by default
+      # This makes explainability the primary format for decision results
+      explainability_data = explainability(verbose: false)
+
+      {
+        # Explainability fields (primary structure)
+        decision: explainability_data[:decision],
+        because: explainability_data[:because],
+        failed_conditions: explainability_data[:failed_conditions],
+        # Additional metadata for completeness
         confidence: @confidence,
         explanations: @explanations,
         evaluations: @evaluations.map(&:to_h),
-        audit_payload: @audit_payload
+        audit_payload: @audit_payload,
+        # Full explainability data (includes rule_traces in verbose mode)
+        explainability: explainability_data
       }
     end
 
+    private
+
+    def all_explainability_results
+      @evaluations.flat_map { |evaluation| extract_explainability_from_evaluation(evaluation) }
+    end
+
+    def extract_explainability_from_evaluation(evaluation)
+      return [] unless evaluation.metadata.is_a?(Hash)
+      return [] unless evaluation.metadata[:explainability]
+
+      explainability_data = normalize_hash_keys(evaluation.metadata[:explainability])
+      rule_traces = reconstruct_rule_traces(explainability_data)
+      evaluator_name = explainability_data[:evaluator_name] || evaluation.evaluator_name
+
+      [Explainability::ExplainabilityResult.new(
+        evaluator_name: evaluator_name,
+        rule_traces: rule_traces
+      )]
+    end
+
+    def normalize_hash_keys(data)
+      return data unless data.is_a?(Hash)
+
+      data.transform_keys(&:to_sym)
+    end
+
+    def reconstruct_rule_traces(explainability_data)
+      rule_traces_data = explainability_data[:rule_traces] || []
+      rule_traces_data.map { |rt_data| reconstruct_rule_trace(rt_data) }
+    end
+
+    def reconstruct_rule_trace(rt_data)
+      normalized_rt = normalize_hash_keys(rt_data)
+      condition_traces = reconstruct_condition_traces(normalized_rt)
+
+      Explainability::RuleTrace.new(
+        rule_id: normalized_rt[:rule_id],
+        matched: normalized_rt[:matched],
+        condition_traces: condition_traces,
+        decision: normalized_rt[:decision],
+        weight: normalized_rt[:weight],
+        reason: normalized_rt[:reason]
+      )
+    end
+
+    def reconstruct_condition_traces(rule_trace_data)
+      condition_traces_data = rule_trace_data[:condition_traces] || []
+      condition_traces_data.map { |ct_data| reconstruct_condition_trace(ct_data) }
+    end
+
+    def reconstruct_condition_trace(ct_data)
+      normalized_ct = normalize_hash_keys(ct_data)
+
+      Explainability::ConditionTrace.new(
+        field: normalized_ct[:field],
+        operator: normalized_ct[:operator],
+        expected_value: normalized_ct[:expected_value],
+        actual_value: normalized_ct[:actual_value],
+        result: normalized_ct[:result]
+      )
+    end
+
+    public
+
+    # @param other [Object] Object to compare
+    # @return [Boolean] true if other is a Decision with same decision, confidence, explanations, evaluations
     def ==(other)
       other.is_a?(Decision) &&
         @decision == other.decision &&
@@ -35,8 +144,8 @@ module DecisionAgent
     private
 
     def validate_confidence!(confidence)
-      c = confidence.to_f
-      raise InvalidConfidenceError, confidence unless c.between?(0.0, 1.0)
+      confidence_value = confidence.to_f
+      raise InvalidConfidenceError, confidence unless confidence_value.between?(0.0, 1.0)
     end
 
     def deep_freeze(obj)

data/lib/decision_agent/dmn/adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "feel/evaluator"
 
 module DecisionAgent

data/lib/decision_agent/dmn/cache.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "digest"
+require "openssl"
 require "zlib"
 
 module DecisionAgent
@@ -144,7 +144,7 @@ module DecisionAgent
       end
 
       def generate_result_key(decision_id, context_hash)
-        Digest::SHA256.hexdigest("#{decision_id}:#{context_hash}")
+        OpenSSL::Digest::SHA256.hexdigest("#{decision_id}:#{context_hash}")
       end
 
       def calculate_hit_rate(hits, misses)

data/lib/decision_agent/dmn/decision_graph.rb

@@ -251,7 +251,8 @@ module DecisionAgent
           "condition",
           context
         )
-      rescue StandardError
+      rescue StandardError => e
+        warn "[DecisionAgent] FEEL condition evaluation failed: #{e.message}"
         false
       end
     end
@@ -277,13 +278,12 @@ module DecisionAgent
           decision_node = graph.get_decision(decision_id)
 
           # Find all information requirements
-          info_reqs = decision_xml.xpath(".//dmn:informationRequirement")
-          info_reqs.each do |req|
+          decision_xml.xpath(".//dmn:informationRequirement").each do |req|
             required_decision = req.at_xpath(".//dmn:requiredDecision")
-            if required_decision
-              required_id = required_decision["href"]&.sub("#", "")
-              decision_node.add_dependency(required_id) if required_id
-            end
+            next unless required_decision
+
+            required_id = required_decision["href"]&.sub("#", "")
+            decision_node.add_dependency(required_id) if required_id
           end
         end
 

data/lib/decision_agent/dmn/decision_tree.rb

@@ -105,15 +105,13 @@ module DecisionAgent
             any_condition_evaluated = true
 
             return traverse(child, context) if result
-            # Condition matched, continue down this branch
-
-            # Condition evaluated to false - check if this child has a false branch
-            # If child has multiple leaf children with no conditions, take the second one
-            if !child.leaf? && child.children.all? { |c| c.condition.nil? && c.leaf? } && child.children.size > 1
-              return child.children[1].decision
-            end
-          rescue StandardError
+
+            # Condition evaluated to false - check for a false branch
+            false_branch = false_branch_decision(child)
+            return false_branch if false_branch
+          rescue StandardError => e
             # If condition evaluation fails, skip this branch
+            warn "[DecisionAgent] Decision tree condition evaluation failed: #{e.message}"
             next
           end
         end
@@ -129,6 +127,16 @@ module DecisionAgent
         nil
       end
 
+      # Check if a child node that evaluated to false has an explicit false branch
+      # (multiple leaf children with no conditions, take the second one)
+      def false_branch_decision(child)
+        return nil if child.leaf?
+        return nil unless child.children.size > 1
+        return nil unless child.children.all? { |c| c.condition.nil? && c.leaf? }
+
+        child.children[1].decision
+      end
+
       def self.build_node(hash)
         node = TreeNode.new(
           id: hash[:id],

data/lib/decision_agent/dmn/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Dmn
     # Base error for all DMN-related errors

data/lib/decision_agent/dmn/exporter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "nokogiri"
 require "set"
 require_relative "errors"

data/lib/decision_agent/dmn/feel/evaluator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../errors"
 require_relative "simple_parser"
 require_relative "parser"
@@ -30,108 +32,15 @@ module DecisionAgent
         # @param field_name [String] The field name being evaluated
         # @param context [Hash] Evaluation context
         # @return [Boolean] Evaluation result
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
         def evaluate(expression, field_name, context)
           return true if expression == "-" # DMN "don't care" marker
 
           # Try Parslet parser first (Phase 2B)
-          if @use_parslet
-            begin
-              expr_key = expression.to_s.strip
-
-              # Check AST cache first
-              ast = @cache_mutex.synchronize do
-                @ast_cache[expr_key]
-              end
-
-              if ast.nil?
-                parse_tree = @parslet_parser.parse(expr_key)
-                ast = @transformer.apply(parse_tree)
-                @cache_mutex.synchronize do
-                  @ast_cache[expr_key] = ast
-                end
-              end
-
-              result = evaluate_ast_node(ast, context)
-              # If result is nil and AST is a simple field reference that doesn't exist in context,
-              # fall back to Phase 2A approach to return condition structure
-              unless result.nil? && ast.is_a?(Hash) && ast[:type] == :field &&
-                     !context.key?(ast[:name]) && !context.key?(ast[:name].to_s) &&
-                     !context.key?(ast[:name].to_sym)
-                return result
-              end
-            # Fall through to Phase 2A
-            rescue Parslet::ParseFailed, FeelParseError, FeelTransformError => e
-              # Fall back to Phase 2A approach
-              warn "Parslet parse failed: #{e.message}, falling back" if ENV["DEBUG_FEEL"]
-            end
-          end
+          parslet_result = try_parslet_evaluate(expression, context) if @use_parslet
+          return parslet_result unless parslet_result == :fallback
 
           # Phase 2A approach: use condition structures
-          # Check cache first (thread-safe)
-          cache_key = "#{expression}::#{field_name}"
-          condition = @cache_mutex.synchronize do
-            @cache[cache_key]
-          end
-
-          return Dsl::ConditionEvaluator.evaluate(condition, context) if condition
-
-          # Parse and translate expression to condition structure
-          expr_str = expression.to_s.strip
-
-          # Check if expression matches any known pattern that can be successfully parsed
-          is_supported = literal?(expr_str) ||
-                         comparison_expression?(expr_str) ||
-                         list_expression?(expr_str) ||
-                         range_expression?(expr_str)
-
-          # For SimpleParser, check if it can actually parse successfully
-          if SimpleParser.can_parse?(expr_str)
-            begin
-              @simple_parser.parse(expr_str)
-              is_supported = true
-            rescue FeelParseError
-              # SimpleParser says it can parse, but actually can't - not supported
-              is_supported = false
-            end
-          end
-          # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-
-          condition = parse_expression_to_condition(expression, field_name, context)
-
-          # If parse_expression_to_condition returned nil, create default condition structure
-          unless condition.is_a?(Hash)
-            condition = {
-              "field" => field_name,
-              "op" => "eq",
-              "value" => parse_value(expr_str)
-            }
-          end
-
-          # Store in cache (thread-safe)
-          @cache_mutex.synchronize do
-            @cache[cache_key] = condition
-          end
-
-          # For completely unsupported expressions (no patterns matched), return condition structure
-          # This allows fallback to literal equality for unknown syntax
-          return condition unless is_supported
-
-          # Delegate to existing ConditionEvaluator for supported expressions
-          evaluation_result = Dsl::ConditionEvaluator.evaluate(condition, context)
-
-          # If evaluation returns false for a simple equality check and the field doesn't exist in context,
-          # treat as unsupported expression and return condition structure (fallback behavior)
-          if evaluation_result == false && condition["op"] == "eq"
-            field_key = condition["field"]
-            field_exists = context.key?(field_key) || context.key?(field_key.to_s) || context.key?(field_key.to_sym)
-            return condition unless field_exists
-          end
-
-          # If evaluation returns nil, return condition structure as fallback
-          return condition if evaluation_result.nil?
-
-          evaluation_result
+          evaluate_phase2a(expression, field_name, context)
         end
 
         # Parse FEEL expression into operator and value (for internal use by Adapter)
@@ -167,6 +76,93 @@ module DecisionAgent
 
         private
 
+        # Attempt evaluation via Parslet parser (Phase 2B)
+        # Returns :fallback if Parslet cannot handle this expression
+        def try_parslet_evaluate(expression, context)
+          ast = cached_parslet_ast(expression.to_s.strip)
+          result = evaluate_ast_node(ast, context)
+
+          # If result is nil for a missing field reference, fall back to Phase 2A
+          return :fallback if result.nil? && unresolved_field_reference?(ast, context)
+
+          result
+        rescue Parslet::ParseFailed, FeelParseError, FeelTransformError => e
+          warn "Parslet parse failed: #{e.message}, falling back" if ENV["DEBUG_FEEL"]
+          :fallback
+        end
+
+        # Fetch or build Parslet AST with thread-safe caching
+        def cached_parslet_ast(expr_key)
+          ast = @cache_mutex.synchronize { @ast_cache[expr_key] }
+          return ast if ast
+
+          parse_tree = @parslet_parser.parse(expr_key)
+          ast = @transformer.apply(parse_tree)
+          @cache_mutex.synchronize { @ast_cache[expr_key] = ast }
+          ast
+        end
+
+        def unresolved_field_reference?(ast, context)
+          ast.is_a?(Hash) && ast[:type] == :field &&
+            !context.key?(ast[:name]) && !context.key?(ast[:name].to_s) &&
+            !context.key?(ast[:name].to_sym)
+        end
+
+        # Phase 2A evaluation: regex-based patterns with condition structures
+        def evaluate_phase2a(expression, field_name, context)
+          cache_key = "#{expression}::#{field_name}"
+          condition = @cache_mutex.synchronize { @cache[cache_key] }
+          return Dsl::ConditionEvaluator.evaluate(condition, context) if condition
+
+          expr_str = expression.to_s.strip
+          is_supported = expression_supported?(expr_str)
+          condition = build_condition(expression, field_name, expr_str, context)
+
+          @cache_mutex.synchronize { @cache[cache_key] = condition }
+
+          return condition unless is_supported
+
+          evaluate_with_fallback(condition, context)
+        end
+
+        # Check if expression matches any known parseable pattern
+        def expression_supported?(expr_str)
+          supported = literal?(expr_str) || comparison_expression?(expr_str) ||
+                      list_expression?(expr_str) || range_expression?(expr_str)
+
+          return supported unless SimpleParser.can_parse?(expr_str)
+
+          @simple_parser.parse(expr_str)
+          true
+        rescue FeelParseError
+          false
+        end
+
+        # Build a condition structure from expression, with fallback to default equality
+        def build_condition(expression, field_name, expr_str, context)
+          condition = parse_expression_to_condition(expression, field_name, context)
+          return condition if condition.is_a?(Hash)
+
+          { "field" => field_name, "op" => "eq", "value" => parse_value(expr_str) }
+        end
+
+        # Evaluate condition with fallback to condition structure when result is ambiguous
+        def evaluate_with_fallback(condition, context)
+          evaluation_result = Dsl::ConditionEvaluator.evaluate(condition, context)
+
+          return condition if evaluation_result.nil?
+          return condition if equality_on_missing_field?(evaluation_result, condition, context)
+
+          evaluation_result
+        end
+
+        def equality_on_missing_field?(result, condition, context)
+          return false unless result == false && condition["op"] == "eq"
+
+          field_key = condition["field"]
+          !context.key?(field_key) && !context.key?(field_key.to_s) && !context.key?(field_key.to_sym)
+        end
+
         def literal?(expr)
           # Quoted string
           return true if expr.start_with?('"') && expr.end_with?('"')
@@ -253,15 +249,37 @@ module DecisionAgent
           max_val = parse_value(range_match[3])
           inclusive_end = range_match[4] == "]"
 
-          # For Phase 2A, we only support fully inclusive ranges
-          # Map to 'between' operator
+          # For Phase 2A, we support fully inclusive ranges with 'between' operator
           if inclusive_start && inclusive_end
             { operator: "between", value: [min_val, max_val] }
           else
-            # Fall back to complex condition (Phase 2B)
-            raise FeelParseError,
-                  "Half-open ranges not yet supported: #{expr}. " \
-                  "Use [min..max] for inclusive ranges."
+            # For half-open ranges, convert to inclusive by adjusting bounds
+            # [min..max) becomes [min..max-1] (if max is integer) or use compound conditions
+            # For simplicity, we'll convert to inclusive ranges with adjusted bounds
+            # This is a pragmatic approach for Phase 2A
+            adjusted_min = if inclusive_start
+                             min_val
+                           elsif min_val.is_a?(Integer)
+                             min_val + 1
+                           else
+                             min_val + 0.0001
+                           end
+            adjusted_max = if inclusive_end
+                             max_val
+                           elsif max_val.is_a?(Integer)
+                             max_val - 1
+                           else
+                             max_val - 0.0001
+                           end
+
+            # Ensure adjusted range is valid
+            if adjusted_min <= adjusted_max
+              { operator: "between", value: [adjusted_min, adjusted_max] }
+            else
+              # Invalid range, fall back to error
+              raise FeelParseError,
+                    "Invalid half-open range: #{expr}. Range would be empty after adjustment."
+            end
           end
         end
 
@@ -573,22 +591,20 @@ module DecisionAgent
 
         # Evaluate function call
         def evaluate_function_call(node, context)
-          # Extract function name - could be a string or a field node
-          function_name = if node[:name].is_a?(Hash)
-                            if node[:name][:type] == :field
-                              node[:name][:name]
-                            else
-                              node[:name][:name] || node[:name][:identifier] || node[:name].to_s
-                            end
-                          else
-                            node[:name]
-                          end
-
+          function_name = extract_function_name(node[:name])
           args = Array(node[:arguments]).map { |arg| evaluate_ast_node(arg, context) }
 
           Functions.execute(function_name.to_s, args, context)
         end
 
+        # Extract function name from a string or structured field node
+        def extract_function_name(name_node)
+          return name_node unless name_node.is_a?(Hash)
+          return name_node[:name] if name_node[:type] == :field
+
+          name_node[:name] || name_node[:identifier] || name_node.to_s
+        end
+
         # Evaluate property access
         def evaluate_property_access(node, context)
           object = evaluate_ast_node(node[:object], context)
@@ -600,7 +616,7 @@ module DecisionAgent
           when Types::Context
             object[property.to_sym]
           else
-            object.respond_to?(property) ? object.send(property) : nil
+            object.respond_to?(property) ? object.public_send(property) : nil
           end
         end
 

data/lib/decision_agent/dmn/feel/functions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../errors"
 require_relative "types"
 

data/lib/decision_agent/dmn/feel/parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "parslet"
 require_relative "../errors"