decision_agent 1.0.1 → 1.2.0

data/lib/decision_agent/auth/rbac_adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     # Base adapter interface for RBAC integration

data/lib/decision_agent/auth/rbac_config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     # Configuration class for RBAC adapter

data/lib/decision_agent/auth/role.rb

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

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,7 +1,12 @@
+# 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
@@ -9,18 +14,26 @@ module DecisionAgent
       @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
 
@@ -40,6 +43,10 @@ module DecisionAgent
       }.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
@@ -124,6 +131,8 @@ module DecisionAgent
 
     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 &&
@@ -135,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"
@@ -11,6 +13,27 @@ module DecisionAgent
         @version_manager = version_manager || Versioning::VersionManager.new
       end
 
+      # Serialize an in-memory DMN Model object to DMN XML.
+      # Unlike #export, this does NOT look up any stored version — it converts
+      # the live model directly.  Use this when saving a new version.
+      # @param model [DecisionAgent::Dmn::Model]
+      # @return [String] DMN XML
+      def serialize_model(model)
+        builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+          xml.definitions(
+            "xmlns" => "https://www.omg.org/spec/DMN/20191111/MODEL/",
+            "xmlns:dmndi" => "https://www.omg.org/spec/DMN/20191111/DMNDI/",
+            "xmlns:dc" => "http://www.omg.org/spec/DMN/20180521/DC/",
+            "id" => "definitions_#{model.id}",
+            "name" => model.name,
+            "namespace" => model.namespace
+          ) do
+            model.decisions.each { |d| serialize_decision_node(xml, d) }
+          end
+        end
+        builder.to_xml
+      end
+
       # Export ruleset to DMN XML
       # @param rule_id [String] Rule ID to export
       # @param output_path [String, nil] Optional file path to write
@@ -31,12 +54,31 @@ module DecisionAgent
 
       private
 
+      def serialize_decision_node(xml, decision)
+        xml.decision(id: decision.id, name: decision.name) do
+          xml.description(decision.description) if decision.description
+          if (dt = decision.decision_table)
+            xml.decisionTable(id: dt.id, hitPolicy: dt.hit_policy) do
+              dt.inputs.each do |inp|
+                xml.input(id: inp.id, label: inp.label) do
+                  xml.inputExpression(typeRef: inp.type_ref) do
+                    xml.text_ inp.expression
+                  end
+                end
+              end
+              dt.outputs.each do |out|
+                xml.output(id: out.id, label: out.label, name: out.name, typeRef: out.type_ref)
+              end
+            end
+          end
+        end
+      end
+
       # Helper to get hash value with both string and symbol key support
       def hash_get(hash, key)
         hash[key.to_s] || hash[key.to_sym]
       end
 
-      # rubocop:disable Metrics/MethodLength
       def convert_to_dmn(rules_json, rule_id)
         # Handle both string and symbol keys
         ruleset_name = rules_json["ruleset"] || rules_json[:ruleset] || rule_id
@@ -83,7 +125,6 @@ module DecisionAgent
 
         builder.to_xml
       end
-      # rubocop:enable Metrics/MethodLength
 
       def extract_inputs(rules)
         # Extract all unique field names used in conditions

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"
@@ -13,7 +15,6 @@ module DecisionAgent
       # Phase 2A: Basic comparisons, ranges, list membership (regex-based)
       # Phase 2B: Arithmetic, logical operators, functions (enhanced parser)
       # Maps FEEL expressions to DecisionAgent ConditionEvaluator
-      # rubocop:disable Metrics/ClassLength
       class Evaluator
         def initialize
           @simple_parser = SimpleParser.new
@@ -30,108 +31,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 +75,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?('"')
@@ -497,7 +492,6 @@ module DecisionAgent
         end
 
         # Evaluate Parslet AST node (Phase 2B - full FEEL support)
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
         def evaluate_ast_node(node, context)
           return node unless node.is_a?(Hash)
 
@@ -553,7 +547,6 @@ module DecisionAgent
             raise FeelEvaluationError, "Unknown AST node type: #{node[:type]}"
           end
         end
-        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
 
         # Get field value from context
         def get_field_value(field_name, context)
@@ -595,22 +588,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)
@@ -622,7 +613,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
 
@@ -813,7 +804,6 @@ module DecisionAgent
           start_check && end_check
         end
       end
-      # rubocop:enable Metrics/ClassLength
     end
   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"