decision_agent 0.2.0 → 1.0.1

data/lib/decision_agent/decision.rb

@@ -14,16 +14,116 @@ 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
+
+    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
+
     def ==(other)
       other.is_a?(Decision) &&
         @decision == other.decision &&

data/lib/decision_agent/dmn/adapter.rb

@@ -0,0 +1,135 @@
+require_relative "feel/evaluator"
+
+module DecisionAgent
+  module Dmn
+    # Converts DMN decision tables to DecisionAgent JSON rule format
+    class Adapter
+      def initialize(decision_table)
+        @table = decision_table
+        @feel = Feel::Evaluator.new
+      end
+
+      # Convert DMN decision table to JSON rules
+      def to_json_rules
+        {
+          "version" => "1.0",
+          "ruleset" => @table.id,
+          "description" => "Converted from DMN decision table",
+          "rules" => convert_rules
+        }
+      end
+
+      private
+
+      def convert_rules
+        @table.rules.map.with_index do |rule, idx|
+          convert_rule(rule, idx)
+        end
+      end
+
+      def convert_rule(rule, idx)
+        {
+          "id" => rule.id || "rule_#{idx + 1}",
+          "if" => build_condition(rule),
+          "then" => build_output(rule),
+          "description" => rule.description
+        }.compact
+      end
+
+      def build_condition(rule)
+        # Build 'all' condition combining all input entries
+        conditions = []
+
+        rule.input_entries.each_with_index do |entry, idx|
+          next if entry == "-" # Skip "don't care" entries
+
+          input = @table.inputs[idx]
+          condition = convert_feel_to_condition(entry, input.expression || input.label)
+          conditions << condition if condition
+        end
+
+        # If no conditions, return a condition that always matches
+        # Use a simple true condition instead of empty "all" array
+        return { "field" => "__always_match__", "op" => "eq", "value" => true } if conditions.empty?
+
+        # If only one condition, return it directly
+        return conditions.first if conditions.size == 1
+
+        # Otherwise, wrap in 'all'
+        { "all" => conditions }
+      end
+
+      def convert_feel_to_condition(feel_expression, field_name)
+        parsed = @feel.parse_expression(feel_expression)
+
+        # Ensure we have valid operator and value
+        operator = parsed[:operator] || "eq"
+        value = parsed[:value]
+
+        # If value is nil, we can't create a valid condition
+        if value.nil?
+          warn "Warning: FEEL expression '#{feel_expression}' parsed to nil value, skipping"
+          return nil
+        end
+
+        {
+          "field" => field_name,
+          "op" => operator,
+          "value" => value
+        }
+      rescue StandardError => e
+        # Log warning and skip invalid expressions
+        warn "Warning: Could not parse FEEL expression '#{feel_expression}': #{e.message}"
+        nil
+      end
+
+      def build_output(rule)
+        # For Phase 2A, we take the first output as the decision
+        # Multi-output support in Phase 2B
+        output_value = rule.output_entries.first
+
+        # Parse FEEL expression in output value (remove quotes from string literals)
+        parsed_value = parse_output_value(output_value)
+
+        # Ensure we always have a valid decision value (not nil or empty string)
+        parsed_value = "no_decision" if parsed_value.nil? || (parsed_value.is_a?(String) && parsed_value.empty?)
+
+        {
+          "decision" => parsed_value,
+          "weight" => 1.0,
+          "reason" => rule.description || "DMN rule #{rule.id} matched"
+        }
+      end
+
+      def parse_output_value(value)
+        # Handle nil values
+        return nil if value.nil?
+
+        # If already not a string, return as-is (number, boolean, etc.)
+        return value unless value.is_a?(String)
+
+        value_str = value.to_s.strip
+
+        # Return nil for empty strings
+        return nil if value_str.empty?
+
+        # Remove quotes from string literals
+        return value_str[1..-2] if value_str.start_with?('"') && value_str.end_with?('"')
+
+        # Try to parse as number
+        if value_str.match?(/^-?\d+\.\d+$/)
+          return value_str.to_f
+        elsif value_str.match?(/^-?\d+$/)
+          return value_str.to_i
+        end
+
+        # Boolean
+        return true if value_str.downcase == "true"
+        return false if value_str.downcase == "false"
+
+        # Return as-is (unquoted string)
+        value_str
+      end
+    end
+  end
+end

data/lib/decision_agent/dmn/cache.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "digest"
+require "zlib"
+
+module DecisionAgent
+  module Dmn
+    # DMN Evaluation Cache
+    # Provides caching for DMN model parsing and evaluation results
+    class EvaluationCache
+      attr_reader :model_cache, :result_cache, :stats
+
+      def initialize(max_model_cache_size: 100, max_result_cache_size: 1000, ttl: 3600)
+        @model_cache = {}
+        @result_cache = {}
+        @max_model_cache_size = max_model_cache_size
+        @max_result_cache_size = max_result_cache_size
+        @ttl = ttl # Time to live in seconds
+        @mutex = Mutex.new
+        @stats = {
+          model_cache_hits: 0,
+          model_cache_misses: 0,
+          result_cache_hits: 0,
+          result_cache_misses: 0
+        }
+      end
+
+      # Cache a parsed DMN model
+      def cache_model(model_id, model)
+        @mutex.synchronize do
+          # Evict oldest if cache is full
+          evict_oldest_model if @model_cache.size >= @max_model_cache_size
+
+          @model_cache[model_id] = {
+            model: model,
+            cached_at: Time.now.to_i
+          }
+        end
+      end
+
+      # Get a cached model
+      def get_model(model_id)
+        @mutex.synchronize do
+          entry = @model_cache[model_id]
+
+          if entry && !expired?(entry[:cached_at])
+            @stats[:model_cache_hits] += 1
+            entry[:model]
+          else
+            @stats[:model_cache_misses] += 1
+            @model_cache.delete(model_id) if entry
+            nil
+          end
+        end
+      end
+
+      # Cache an evaluation result
+      def cache_result(decision_id, context_hash, result)
+        @mutex.synchronize do
+          # Evict oldest if cache is full
+          evict_oldest_result if @result_cache.size >= @max_result_cache_size
+
+          cache_key = generate_result_key(decision_id, context_hash)
+          @result_cache[cache_key] = {
+            result: result,
+            cached_at: Time.now.to_i
+          }
+        end
+      end
+
+      # Get a cached evaluation result
+      def get_result(decision_id, context_hash)
+        @mutex.synchronize do
+          cache_key = generate_result_key(decision_id, context_hash)
+          entry = @result_cache[cache_key]
+
+          if entry && !expired?(entry[:cached_at])
+            @stats[:result_cache_hits] += 1
+            entry[:result]
+          else
+            @stats[:result_cache_misses] += 1
+            @result_cache.delete(cache_key) if entry
+            nil
+          end
+        end
+      end
+
+      # Clear all caches
+      def clear
+        @mutex.synchronize do
+          @model_cache.clear
+          @result_cache.clear
+          @stats.each_key { |k| @stats[k] = 0 }
+        end
+      end
+
+      # Clear model cache
+      def clear_models
+        @mutex.synchronize do
+          @model_cache.clear
+        end
+      end
+
+      # Clear result cache
+      def clear_results
+        @mutex.synchronize do
+          @result_cache.clear
+        end
+      end
+
+      # Get cache statistics
+      def statistics
+        @mutex.synchronize do
+          model_hit_rate = calculate_hit_rate(@stats[:model_cache_hits], @stats[:model_cache_misses])
+          result_hit_rate = calculate_hit_rate(@stats[:result_cache_hits], @stats[:result_cache_misses])
+
+          @stats.merge(
+            model_cache_size: @model_cache.size,
+            result_cache_size: @result_cache.size,
+            model_hit_rate: model_hit_rate,
+            result_hit_rate: result_hit_rate
+          )
+        end
+      end
+
+      private
+
+      def expired?(cached_at)
+        (Time.now.to_i - cached_at) > @ttl
+      end
+
+      def evict_oldest_model
+        return if @model_cache.empty?
+
+        oldest_key = @model_cache.min_by { |_k, v| v[:cached_at] }[0]
+        @model_cache.delete(oldest_key)
+      end
+
+      def evict_oldest_result
+        return if @result_cache.empty?
+
+        oldest_key = @result_cache.min_by { |_k, v| v[:cached_at] }[0]
+        @result_cache.delete(oldest_key)
+      end
+
+      def generate_result_key(decision_id, context_hash)
+        Digest::SHA256.hexdigest("#{decision_id}:#{context_hash}")
+      end
+
+      def calculate_hit_rate(hits, misses)
+        total = hits + misses
+        total.positive? ? (hits.to_f / total * 100).round(2) : 0
+      end
+    end
+
+    # Enhanced DMN Evaluator with Caching
+    class CachedDmnEvaluator
+      attr_reader :cache, :evaluator
+
+      def initialize(dmn_model:, decision_id:, cache: nil, enable_caching: true)
+        @dmn_model = dmn_model
+        @decision_id = decision_id
+        @cache = cache || EvaluationCache.new
+        @enable_caching = enable_caching
+
+        # Create the underlying evaluator
+        @evaluator = Evaluators::DmnEvaluator.new(
+          dmn_model: dmn_model,
+          decision_id: decision_id
+        )
+      end
+
+      # Evaluate with caching
+      def evaluate(context:)
+        return @evaluator.evaluate(context: context) unless @enable_caching
+
+        # Generate context hash for cache key
+        context_hash = generate_context_hash(context)
+
+        # Try to get cached result
+        cached_result = @cache.get_result(@decision_id, context_hash)
+        return cached_result if cached_result
+
+        # Evaluate and cache result
+        result = @evaluator.evaluate(context: context)
+        @cache.cache_result(@decision_id, context_hash, result)
+
+        result
+      end
+
+      # Warm up cache with common inputs
+      def warm_cache(input_samples)
+        input_samples.each do |inputs|
+          context = Context.new(inputs)
+          evaluate(context: context)
+        end
+      end
+
+      # Get cache statistics
+      def cache_stats
+        @cache.statistics
+      end
+
+      # Clear cache
+      def clear_cache
+        @cache.clear_results
+      end
+
+      private
+
+      def generate_context_hash(context)
+        # Create a deterministic hash of the context
+        # Use CRC32 for better performance (much faster than SHA256, still deterministic)
+        data = context.is_a?(Context) ? context.to_h : context
+
+        # For deterministic hashing, sort keys and create a stable representation
+        # Use CRC32 which is faster than SHA256 while still being deterministic
+        sorted_data = data.sort.to_h
+        json_str = sorted_data.to_json
+        Zlib.crc32(json_str)
+      end
+    end
+
+    # FEEL Expression Cache
+    # Caches compiled/parsed FEEL expressions for reuse
+    class FeelExpressionCache
+      def initialize(max_size: 500)
+        @cache = {}
+        @max_size = max_size
+        @mutex = Mutex.new
+        @stats = { hits: 0, misses: 0 }
+      end
+
+      # Cache a parsed FEEL expression
+      def cache_expression(expression_string, parsed_expression)
+        @mutex.synchronize do
+          evict_oldest if @cache.size >= @max_size
+
+          @cache[expression_string] = {
+            expression: parsed_expression,
+            accessed_at: Time.now.to_i,
+            access_count: 0
+          }
+        end
+      end
+
+      # Get a cached expression
+      def get_expression(expression_string)
+        @mutex.synchronize do
+          entry = @cache[expression_string]
+
+          if entry
+            @stats[:hits] += 1
+            entry[:accessed_at] = Time.now.to_i
+            entry[:access_count] += 1
+            entry[:expression]
+          else
+            @stats[:misses] += 1
+            nil
+          end
+        end
+      end
+
+      # Clear cache
+      def clear
+        @mutex.synchronize do
+          @cache.clear
+          @stats[:hits] = 0
+          @stats[:misses] = 0
+        end
+      end
+
+      # Get statistics
+      def statistics
+        @mutex.synchronize do
+          hit_rate = @stats[:hits] + @stats[:misses]
+          hit_rate = hit_rate.positive? ? (@stats[:hits].to_f / hit_rate * 100).round(2) : 0
+
+          {
+            size: @cache.size,
+            hits: @stats[:hits],
+            misses: @stats[:misses],
+            hit_rate: hit_rate,
+            most_accessed: most_accessed_expressions
+          }
+        end
+      end
+
+      private
+
+      def evict_oldest
+        return if @cache.empty?
+
+        # Evict least recently accessed
+        oldest_key = @cache.min_by { |_k, v| v[:accessed_at] }[0]
+        @cache.delete(oldest_key)
+      end
+
+      def most_accessed_expressions
+        @cache.sort_by { |_k, v| -v[:access_count] }.first(5).map do |expr, data|
+          { expression: expr, count: data[:access_count] }
+        end
+      end
+    end
+  end
+end