decision_agent 0.3.0 → 1.0.1

data/lib/decision_agent/data_enrichment/circuit_breaker.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module DecisionAgent
+  module DataEnrichment
+    # Circuit breaker pattern for resilience
+    #
+    # Prevents cascading failures by opening the circuit after N failures
+    class CircuitBreaker
+      include MonitorMixin
+
+      # Circuit states
+      CLOSED = :closed    # Normal operation
+      OPEN = :open        # Circuit is open, failing fast
+      HALF_OPEN = :half_open # Testing if service recovered
+
+      def initialize(failure_threshold: 5, timeout: 60, success_threshold: 2)
+        super()
+        @failure_threshold = failure_threshold
+        @timeout = timeout
+        @success_threshold = success_threshold
+        @state = CLOSED
+        @failure_count = 0
+        @success_count = 0
+        @last_failure_time = nil
+      end
+
+      # Execute block with circuit breaker protection
+      #
+      # @yield Block to execute
+      # @return [Object] Result of block execution
+      # @raise [CircuitOpenError] If circuit is open
+      def call
+        synchronize do
+          check_state
+          raise CircuitOpenError, "Circuit is open" if @state == OPEN
+        end
+
+        begin
+          result = yield
+          record_success
+          result
+        rescue StandardError => e
+          record_failure
+          raise e
+        end
+      end
+
+      # Check if circuit is open
+      #
+      # @return [Boolean]
+      def open?
+        synchronize do
+          check_state
+          @state == OPEN
+        end
+      end
+
+      # Reset circuit breaker to closed state
+      def reset
+        synchronize do
+          @state = CLOSED
+          @failure_count = 0
+          @success_count = 0
+          @last_failure_time = nil
+        end
+      end
+
+      # Get current state
+      #
+      # @return [Symbol] Current state
+      def state
+        synchronize do
+          check_state
+          @state
+        end
+      end
+
+      private
+
+      def check_state
+        case @state
+        when OPEN
+          # Check if timeout has elapsed, move to half-open
+          if @last_failure_time && (Time.now - @last_failure_time) >= @timeout
+            @state = HALF_OPEN
+            @success_count = 0
+          end
+        when HALF_OPEN
+          # State remains half-open until success threshold is met
+        when CLOSED
+          # State remains closed until failure threshold is met
+        end
+      end
+
+      def record_success
+        synchronize do
+          case @state
+          when HALF_OPEN
+            @success_count += 1
+            if @success_count >= @success_threshold
+              @state = CLOSED
+              @failure_count = 0
+              @success_count = 0
+            end
+          when CLOSED
+            @failure_count = 0 # Reset failure count on success
+          end
+        end
+      end
+
+      def record_failure
+        synchronize do
+          @failure_count += 1
+          @last_failure_time = Time.now
+
+          case @state
+          when HALF_OPEN
+            # Failures in half-open state immediately open the circuit
+            @state = OPEN
+            @success_count = 0
+          when CLOSED
+            # Open circuit if failure threshold is met
+            @state = OPEN if @failure_count >= @failure_threshold
+          end
+        end
+      end
+
+      # Error raised when circuit is open
+      class CircuitOpenError < StandardError
+      end
+    end
+  end
+end

data/lib/decision_agent/data_enrichment/client.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "base64"
+require_relative "cache_adapter"
+require_relative "cache/memory_adapter"
+require_relative "circuit_breaker"
+require_relative "errors"
+
+module DecisionAgent
+  module DataEnrichment
+    # HTTP client for data enrichment requests
+    class Client
+      # Error classes
+      class RequestError < StandardError
+        attr_reader :status_code, :response_body
+
+        def initialize(message, status_code: nil, response_body: nil)
+          super(message)
+          @status_code = status_code
+          @response_body = response_body
+        end
+      end
+
+      class TimeoutError < RequestError
+      end
+
+      class NetworkError < RequestError
+      end
+
+      attr_reader :config, :cache_adapter, :circuit_breaker
+
+      def initialize(config:, cache_adapter: nil, circuit_breaker: nil)
+        @config = config
+        @cache_adapter = cache_adapter || Cache::MemoryAdapter.new
+        @circuit_breakers = {}
+        @circuit_breaker_default = circuit_breaker || CircuitBreaker.new
+        @circuit_breaker = @circuit_breaker_default
+      end
+
+      # Fetch data from configured endpoint
+      #
+      # @param endpoint_name [Symbol] Endpoint identifier
+      # @param params [Hash] Request parameters
+      # @param use_cache [Boolean] Whether to use cache (default: true)
+      # @return [Hash] Response data
+      # @raise [RequestError] If request fails
+      def fetch(endpoint_name, params: {}, use_cache: true)
+        endpoint_config = @config.endpoint(endpoint_name)
+        raise ArgumentError, "Unknown endpoint: #{endpoint_name}" unless endpoint_config
+
+        # Generate cache key
+        cache_key = @cache_adapter.cache_key(endpoint_name, params)
+
+        # Check cache first
+        if use_cache
+          cached = @cache_adapter.get(cache_key)
+          return cached if cached
+        end
+
+        # Execute request with circuit breaker
+        circuit_breaker = get_circuit_breaker(endpoint_name)
+        begin
+          response_data = circuit_breaker.call do
+            execute_request(endpoint_name, endpoint_config, params)
+          end
+        rescue CircuitBreaker::CircuitOpenError => e
+          # Try to return cached data on circuit open
+          cached = @cache_adapter.get(cache_key) if use_cache
+          return cached if cached
+
+          raise RequestError, "Circuit breaker is open for #{endpoint_name}: #{e.message}"
+        end
+
+        # Cache response
+        @cache_adapter.set(cache_key, response_data, endpoint_config[:cache][:ttl]) if use_cache && endpoint_config[:cache][:ttl].positive?
+
+        response_data
+      end
+
+      # Clear cache for endpoint
+      #
+      # @param endpoint_name [Symbol, nil] Endpoint identifier, or nil to clear all
+      def clear_cache(endpoint_name = nil)
+        if endpoint_name
+          # Clear cache entries for this endpoint (requires cache adapter support)
+          # For now, just clear all if endpoint-specific clearing isn't supported
+        end
+        @cache_adapter.clear
+      end
+
+      private
+
+      def execute_request(endpoint_name, endpoint_config, params)
+        uri = URI(endpoint_config[:url])
+        method = endpoint_config[:method]
+        timeout = endpoint_config[:timeout]
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.read_timeout = timeout
+        http.open_timeout = timeout
+
+        request = build_request(uri, method, endpoint_config, params)
+
+        response = http.request(request)
+
+        handle_response(response, endpoint_name)
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise TimeoutError, "Request timeout for #{endpoint_name}: #{e.message}"
+      rescue StandardError => e
+        raise NetworkError, "Network error for #{endpoint_name}: #{e.message}"
+      end
+
+      def build_request(uri, method, endpoint_config, params)
+        headers = endpoint_config[:headers].dup || {}
+        apply_auth(headers, endpoint_config[:auth])
+
+        case method
+        when :get
+          # Add params to query string for GET requests
+          if params.any?
+            query_string = URI.encode_www_form(params)
+            uri_with_query = URI("#{uri}?#{query_string}")
+            request = Net::HTTP::Get.new(uri_with_query)
+          else
+            request = Net::HTTP::Get.new(uri)
+          end
+        when :post
+          request = Net::HTTP::Post.new(uri)
+          request.body = params.to_json
+          headers["Content-Type"] ||= "application/json"
+        when :put
+          request = Net::HTTP::Put.new(uri)
+          request.body = params.to_json
+          headers["Content-Type"] ||= "application/json"
+        when :delete
+          request = Net::HTTP::Delete.new(uri)
+        else
+          raise ArgumentError, "Unsupported HTTP method: #{method}"
+        end
+
+        headers.each { |k, v| request[k] = v }
+        request
+      end
+
+      def apply_auth(headers, auth_config)
+        return unless auth_config
+
+        case auth_config[:type]
+        when :api_key
+          header_name = auth_config[:header] || "X-API-Key"
+          api_key = get_secret(auth_config[:secret_key] || "API_KEY")
+          headers[header_name] = api_key
+        when :basic
+          username = get_secret(auth_config[:username_key] || "USERNAME")
+          password = get_secret(auth_config[:password_key] || "PASSWORD")
+          credentials = Base64.strict_encode64("#{username}:#{password}")
+          headers["Authorization"] = "Basic #{credentials}"
+        when :bearer
+          token = get_secret(auth_config[:token_key] || "TOKEN")
+          headers["Authorization"] = "Bearer #{token}"
+        end
+      end
+
+      def get_secret(key)
+        # Try environment variable first
+        return ENV[key] if ENV.key?(key)
+        return ENV[key.upcase] if ENV.key?(key.upcase)
+
+        # Could extend to support vault integration here
+        raise ArgumentError, "Secret not found: #{key}. Set environment variable #{key.upcase}"
+      end
+
+      def handle_response(response, endpoint_name)
+        case response.code.to_i
+        when 200..299
+          parse_response(response)
+        when 400..499
+          raise RequestError.new(
+            "Client error for #{endpoint_name}: HTTP #{response.code}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        when 500..599
+          raise RequestError.new(
+            "Server error for #{endpoint_name}: HTTP #{response.code}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        else
+          raise RequestError.new(
+            "Unexpected response for #{endpoint_name}: HTTP #{response.code}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        end
+      end
+
+      def parse_response(response)
+        content_type = response["Content-Type"] || ""
+        body = response.body
+
+        return {} if body.nil? || body.empty?
+
+        if content_type.include?("application/json")
+          JSON.parse(body, symbolize_names: true)
+        else
+          { body: body, content_type: content_type }
+        end
+      end
+
+      def get_circuit_breaker(endpoint_name)
+        @circuit_breakers[endpoint_name] ||= @circuit_breaker_default.dup
+      end
+    end
+  end
+end

data/lib/decision_agent/data_enrichment/config.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module DataEnrichment
+    # Configuration for data enrichment endpoints
+    class Config
+      attr_accessor :endpoints, :default_timeout, :default_retry, :default_cache
+
+      def initialize
+        @endpoints = {}
+        @default_timeout = 5 # seconds
+        @default_retry = { max_attempts: 3, backoff: :exponential }
+        @default_cache = { ttl: 3600, adapter: :memory }
+      end
+
+      # Add or update an endpoint configuration
+      #
+      # @param name [Symbol] Endpoint identifier
+      # @param url [String] Base URL for the endpoint
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+      # @param auth [Hash] Authentication configuration
+      # @param cache [Hash] Cache configuration
+      # @param retry_config [Hash] Retry configuration
+      # @param timeout [Integer] Request timeout in seconds
+      # @param headers [Hash] Default headers
+      # @param rate_limit [Hash] Rate limiting configuration
+      #
+      # @example
+      #   config.add_endpoint(:credit_bureau,
+      #     url: "https://api.creditbureau.com/v1/score",
+      #     method: :post,
+      #     auth: { type: :api_key, header: "X-API-Key" },
+      #     cache: { ttl: 3600, adapter: :redis },
+      #     retry_config: { max_attempts: 3, backoff: :exponential }
+      #   )
+      def add_endpoint(name, url:, method: :get, auth: nil, cache: nil, retry_config: nil, timeout: nil, headers: {}, rate_limit: nil) # rubocop:disable Metrics/ParameterLists
+        @endpoints[name.to_sym] = {
+          url: url,
+          method: method.to_sym,
+          auth: auth,
+          cache: cache || @default_cache.dup,
+          retry: retry_config || @default_retry.dup,
+          timeout: timeout || @default_timeout,
+          headers: headers,
+          rate_limit: rate_limit
+        }
+      end
+
+      # Get endpoint configuration
+      #
+      # @param name [Symbol] Endpoint identifier
+      # @return [Hash, nil] Endpoint configuration or nil if not found
+      def endpoint(name)
+        @endpoints[name.to_sym]
+      end
+
+      # Check if endpoint exists
+      #
+      # @param name [Symbol] Endpoint identifier
+      # @return [Boolean]
+      def endpoint?(name)
+        @endpoints.key?(name.to_sym)
+      end
+
+      # Remove endpoint configuration
+      #
+      # @param name [Symbol] Endpoint identifier
+      def remove_endpoint(name)
+        @endpoints.delete(name.to_sym)
+      end
+
+      # Clear all endpoint configurations
+      def clear
+        @endpoints.clear
+      end
+    end
+  end
+end

data/lib/decision_agent/data_enrichment/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module DataEnrichment
+    # Base error class for data enrichment
+    class Error < StandardError
+    end
+
+    # Error raised when endpoint is not configured
+    class EndpointNotFoundError < Error
+    end
+
+    # Error raised when request fails
+    class RequestError < Error
+      attr_reader :status_code, :response_body
+
+      def initialize(message, status_code: nil, response_body: nil)
+        super(message)
+        @status_code = status_code
+        @response_body = response_body
+      end
+    end
+
+    # Error raised when request times out
+    class TimeoutError < RequestError
+    end
+
+    # Error raised when network error occurs
+    class NetworkError < RequestError
+    end
+
+    # Error raised when circuit breaker is open
+    class CircuitOpenError < Error
+    end
+  end
+end

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/feel/evaluator.rb

@@ -253,15 +253,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