decision_agent 0.1.1 → 0.1.3

data/bin/decision_agent

@@ -24,11 +24,14 @@ def print_help
       decision_agent version
 
     For more information, visit:
-    https://github.com/yourusername/decision_agent
+    https://github.com/samaswin87/decision_agent
   HELP
 end
 
 def start_web_ui(port = 4567)
+  # Ruby 4.0 compatibility: Puma expects Bundler::ORIGINAL_ENV which was removed
+  Bundler.const_set(:ORIGINAL_ENV, ENV.to_h.dup) if defined?(Bundler) && !Bundler.const_defined?(:ORIGINAL_ENV)
+
   puts "🎯 Starting DecisionAgent Rule Builder..."
   puts "📍 Server: http://localhost:#{port}"
   puts "⚡️ Press Ctrl+C to stop"
@@ -55,19 +58,16 @@ def validate_file(filepath)
     puts "   Version: #{data['version'] || data[:version]}"
     puts "   Ruleset: #{data['ruleset'] || data[:ruleset]}"
     puts "   Rules: #{data['rules']&.size || 0}"
-
   rescue JSON::ParserError => e
     puts "❌ JSON Parsing Error:"
     puts "   #{e.message}"
     exit 1
-
   rescue DecisionAgent::InvalidRuleDslError => e
     puts "❌ Validation Failed:"
     puts ""
     puts e.message
     exit 1
-
-  rescue => e
+  rescue StandardError => e
     puts "❌ Unexpected Error:"
     puts "   #{e.message}"
     exit 1

data/lib/decision_agent/agent.rb

@@ -1,5 +1,6 @@
 require "digest"
 require "json"
+require "json/canonicalization"
 
 module DecisionAgent
   class Agent
@@ -11,6 +12,9 @@ module DecisionAgent
       @audit_adapter = audit_adapter || Audit::NullAdapter.new
 
       validate_configuration!
+
+      # Freeze instance variables for thread-safety
+      @evaluators.freeze
     end
 
     def decide(context:, feedback: {})
@@ -20,6 +24,9 @@ module DecisionAgent
 
       raise NoEvaluationsError if evaluations.empty?
 
+      # Validate all evaluations for correctness and thread-safety
+      EvaluationValidator.validate_all!(evaluations)
+
       scored_result = @scoring_strategy.score(evaluations)
 
       decision_value = scored_result[:decision]
@@ -51,32 +58,24 @@ module DecisionAgent
     private
 
     def validate_configuration!
-      if @evaluators.empty?
-        raise InvalidConfigurationError, "At least one evaluator is required"
-      end
+      raise InvalidConfigurationError, "At least one evaluator is required" if @evaluators.empty?
 
       @evaluators.each do |evaluator|
-        unless evaluator.respond_to?(:evaluate)
-          raise InvalidEvaluatorError
-        end
+        raise InvalidEvaluatorError unless evaluator.respond_to?(:evaluate)
       end
 
-      unless @scoring_strategy.respond_to?(:score)
-        raise InvalidScoringStrategyError
-      end
+      raise InvalidScoringStrategyError unless @scoring_strategy.respond_to?(:score)
 
-      unless @audit_adapter.respond_to?(:record)
-        raise InvalidAuditAdapterError
-      end
+      return if @audit_adapter.respond_to?(:record)
+
+      raise InvalidAuditAdapterError
     end
 
     def collect_evaluations(context, feedback)
       @evaluators.map do |evaluator|
-        begin
-          evaluator.evaluate(context, feedback: feedback)
-        rescue => e
-          nil
-        end
+        evaluator.evaluate(context, feedback: feedback)
+      rescue StandardError
+        nil
       end.compact
     end
 
@@ -132,16 +131,10 @@ module DecisionAgent
       Digest::SHA256.hexdigest(canonical)
     end
 
+    # Uses RFC 8785 (JSON Canonicalization Scheme) for deterministic JSON serialization
+    # This is the industry standard for cryptographic hashing of JSON data
     def canonical_json(obj)
-      case obj
-      when Hash
-        sorted = obj.keys.sort.map { |k| [k.to_s, canonical_json(obj[k])] }.to_h
-        JSON.generate(sorted, quirks_mode: false)
-      when Array
-        JSON.generate(obj.map { |v| canonical_json(v) }, quirks_mode: false)
-      else
-        obj.to_s
-      end
+      obj.to_json_c14n
     end
   end
 end

data/lib/decision_agent/audit/null_adapter.rb

@@ -1,8 +1,7 @@
 module DecisionAgent
   module Audit
     class NullAdapter < Adapter
-      def record(decision, context)
-      end
+      def record(decision, context); end
     end
   end
 end

data/lib/decision_agent/decision.rb

@@ -10,6 +10,8 @@ module DecisionAgent
       @explanations = Array(explanations).map(&:freeze).freeze
       @evaluations = Array(evaluations).freeze
       @audit_payload = deep_freeze(audit_payload)
+
+      freeze
     end
 
     def to_h
@@ -34,7 +36,7 @@ module DecisionAgent
 
     def validate_confidence!(confidence)
       c = confidence.to_f
-      raise InvalidConfidenceError.new(confidence) unless c >= 0.0 && c <= 1.0
+      raise InvalidConfidenceError, confidence unless c.between?(0.0, 1.0)
     end
 
     def deep_freeze(obj)

data/lib/decision_agent/dsl/condition_evaluator.rb

@@ -21,13 +21,12 @@ module DecisionAgent
         end
       end
 
-      private
-
       # Evaluates 'all' condition - returns true only if ALL sub-conditions are true
       # Empty array returns true (vacuous truth)
       def self.evaluate_all(conditions, context)
         return true if conditions.is_a?(Array) && conditions.empty?
         return false unless conditions.is_a?(Array)
+
         conditions.all? { |cond| evaluate(cond, context) }
       end
 
@@ -35,6 +34,7 @@ module DecisionAgent
       # Empty array returns false (no options to match)
       def self.evaluate_any(conditions, context)
         return false unless conditions.is_a?(Array)
+
         conditions.any? { |cond| evaluate(cond, context) }
       end
 
@@ -117,6 +117,7 @@ module DecisionAgent
         keys = key_path.to_s.split(".")
         keys.reduce(hash) do |memo, key|
           return nil unless memo.is_a?(Hash)
+
           memo[key] || memo[key.to_sym]
         end
       end
@@ -126,7 +127,7 @@ module DecisionAgent
       def self.comparable?(val1, val2)
         (val1.is_a?(Numeric) || val1.is_a?(String)) &&
           (val2.is_a?(Numeric) || val2.is_a?(String)) &&
-          val1.class == val2.class
+          val1.instance_of?(val2.class)
       end
     end
   end

data/lib/decision_agent/dsl/rule_parser.rb

@@ -13,14 +13,12 @@ module DecisionAgent
       rescue JSON::ParserError => e
         raise InvalidRuleDslError, "Invalid JSON syntax: #{e.message}\n\n" \
                                    "Please ensure your JSON is properly formatted. " \
-                                   "Common issues:\n" \
-                                   "  - Missing or extra commas\n" \
-                                   "  - Unquoted keys or values\n" \
-                                   "  - Unmatched brackets or braces"
+                                   "Common issues:\n  " \
+                                   "- Missing or extra commas\n  " \
+                                   "- Unquoted keys or values\n  " \
+                                   "- Unmatched brackets or braces"
       end
 
-      private
-
       def self.parse_json(input)
         if input.is_a?(String)
           JSON.parse(input)

data/lib/decision_agent/dsl/schema_validator.rb

@@ -31,18 +31,18 @@ module DecisionAgent
       private
 
       def validate_root_structure
-        unless @data.is_a?(Hash)
-          @errors << "Root element must be a hash/object, got #{@data.class}"
-          return
-        end
+        return if @data.is_a?(Hash)
+
+        @errors << "Root element must be a hash/object, got #{@data.class}"
+        nil
       end
 
       def validate_version
         return if @errors.any? # Skip if root structure is invalid
 
-        unless @data.key?("version") || @data.key?(:version)
-          @errors << "Missing required field 'version'. Example: { \"version\": \"1.0\", ... }"
-        end
+        return if @data.key?("version") || @data.key?(:version)
+
+        @errors << "Missing required field 'version'. Example: { \"version\": \"1.0\", ... }"
       end
 
       def validate_rules_array
@@ -55,9 +55,9 @@ module DecisionAgent
           return
         end
 
-        unless rules.is_a?(Array)
-          @errors << "Field 'rules' must be an array, got #{rules.class}. Example: \"rules\": [...]"
-        end
+        return if rules.is_a?(Array)
+
+        @errors << "Field 'rules' must be an array, got #{rules.class}. Example: \"rules\": [...]"
       end
 
       def validate_each_rule
@@ -93,9 +93,9 @@ module DecisionAgent
           return
         end
 
-        unless rule_id.is_a?(String) || rule_id.is_a?(Symbol)
-          @errors << "#{rule_path}: Field 'id' must be a string, got #{rule_id.class}"
-        end
+        return if rule_id.is_a?(String) || rule_id.is_a?(Symbol)
+
+        @errors << "#{rule_path}: Field 'id' must be a string, got #{rule_id.class}"
       end
 
       def validate_if_clause(rule, rule_path)
@@ -150,9 +150,7 @@ module DecisionAgent
         value = condition["value"] || condition[:value]
 
         # Validate field
-        unless field
-          @errors << "#{path}: Field condition missing 'field' key"
-        end
+        @errors << "#{path}: Field condition missing 'field' key" unless field
 
         # Validate operator
         unless operator
@@ -174,10 +172,10 @@ module DecisionAgent
       def validate_operator(operator, path)
         operator_str = operator.to_s
 
-        unless SUPPORTED_OPERATORS.include?(operator_str)
-          @errors << "#{path}: Unsupported operator '#{operator}'. " \
-                     "Supported operators: #{SUPPORTED_OPERATORS.join(', ')}"
-        end
+        return if SUPPORTED_OPERATORS.include?(operator_str)
+
+        @errors << "#{path}: Unsupported operator '#{operator}'. " \
+                   "Supported operators: #{SUPPORTED_OPERATORS.join(', ')}"
       end
 
       def validate_field_path(field, path)
@@ -191,11 +189,11 @@ module DecisionAgent
         # Validate dot-notation
         parts = field.split(".")
 
-        if parts.any?(&:empty?)
-          @errors << "#{path}: Invalid field path '#{field}'. " \
-                     "Dot-notation paths cannot have empty segments. " \
-                     "Example: 'user.profile.role'"
-        end
+        return unless parts.any?(&:empty?)
+
+        @errors << "#{path}: Invalid field path '#{field}'. " \
+                   "Dot-notation paths cannot have empty segments. " \
+                   "Example: 'user.profile.role'"
       end
 
       def validate_all_condition(condition, path)
@@ -241,9 +239,7 @@ module DecisionAgent
         # Validate decision
         decision = then_clause["decision"] || then_clause[:decision]
 
-        unless decision
-          @errors << "#{rule_path}.then: Missing required field 'decision'"
-        end
+        @errors << "#{rule_path}.then: Missing required field 'decision'" unless decision
 
         # Validate optional weight
         weight = then_clause["weight"] || then_clause[:weight]
@@ -257,9 +253,9 @@ module DecisionAgent
         # Validate optional reason
         reason = then_clause["reason"] || then_clause[:reason]
 
-        if reason && !reason.is_a?(String)
-          @errors << "#{rule_path}.then.reason: Must be a string, got #{reason.class}"
-        end
+        return unless reason && !reason.is_a?(String)
+
+        @errors << "#{rule_path}.then.reason: Must be a string, got #{reason.class}"
       end
 
       def format_errors

data/lib/decision_agent/errors.rb

@@ -3,13 +3,13 @@ module DecisionAgent
 
   class InvalidRuleDslError < Error
     def initialize(message = "Invalid rule DSL structure")
-      super(message)
+      super
     end
   end
 
   class NoEvaluationsError < Error
     def initialize(message = "No evaluators returned a decision")
-      super(message)
+      super
     end
   end
 
@@ -26,25 +26,25 @@ module DecisionAgent
 
   class InvalidConfigurationError < Error
     def initialize(message = "Invalid agent configuration")
-      super(message)
+      super
     end
   end
 
   class InvalidEvaluatorError < Error
     def initialize(message = "Evaluator must respond to #evaluate")
-      super(message)
+      super
     end
   end
 
   class InvalidScoringStrategyError < Error
     def initialize(message = "Scoring strategy must respond to #score")
-      super(message)
+      super
     end
   end
 
   class InvalidAuditAdapterError < Error
     def initialize(message = "Audit adapter must respond to #record")
-      super(message)
+      super
     end
   end
 
@@ -59,4 +59,19 @@ module DecisionAgent
       super("Weight must be between 0.0 and 1.0, got: #{weight}")
     end
   end
+
+  class NotFoundError < Error
+    def initialize(message = "Resource not found")
+      super
+    end
+  end
+
+  class ValidationError < Error
+    def initialize(message = "Validation failed")
+      super
+    end
+  end
+
+  # Alias for backward compatibility and clearer naming
+  ConfigurationError = InvalidConfigurationError
 end

data/lib/decision_agent/evaluation.rb

@@ -10,6 +10,8 @@ module DecisionAgent
       @reason = reason.to_s.freeze
       @evaluator_name = evaluator_name.to_s.freeze
       @metadata = deep_freeze(metadata)
+
+      freeze
     end
 
     def to_h
@@ -35,7 +37,7 @@ module DecisionAgent
 
     def validate_weight!(weight)
       w = weight.to_f
-      raise InvalidWeightError.new(weight) unless w >= 0.0 && w <= 1.0
+      raise InvalidWeightError, weight unless w.between?(0.0, 1.0)
     end
 
     def deep_freeze(obj)

data/lib/decision_agent/evaluation_validator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  # Validates evaluation objects for correctness and thread-safety
+  class EvaluationValidator
+    class ValidationError < StandardError; end
+
+    # Validates a single evaluation
+    # @param evaluation [Evaluation] the evaluation to validate
+    # @raise [ValidationError] if validation fails
+    def self.validate!(evaluation)
+      raise ValidationError, "Evaluation cannot be nil" if evaluation.nil?
+      raise ValidationError, "Evaluation must be an Evaluation instance" unless evaluation.is_a?(Evaluation)
+
+      validate_decision!(evaluation.decision)
+      validate_weight!(evaluation.weight)
+      validate_reason!(evaluation.reason)
+      validate_evaluator_name!(evaluation.evaluator_name)
+      validate_frozen!(evaluation)
+
+      true
+    end
+
+    # Validates an array of evaluations
+    # @param evaluations [Array<Evaluation>] the evaluations to validate
+    # @raise [ValidationError] if validation fails
+    def self.validate_all!(evaluations)
+      raise ValidationError, "Evaluations must be an Array" unless evaluations.is_a?(Array)
+      raise ValidationError, "Evaluations array cannot be empty" if evaluations.empty?
+
+      evaluations.each_with_index do |evaluation, index|
+        validate!(evaluation)
+      rescue ValidationError => e
+        raise ValidationError, "Validation failed for evaluation at index #{index}: #{e.message}"
+      end
+
+      true
+    end
+
+    private_class_method def self.validate_decision!(decision)
+      raise ValidationError, "Decision cannot be nil" if decision.nil?
+      raise ValidationError, "Decision must be a String" unless decision.is_a?(String)
+      raise ValidationError, "Decision cannot be empty" if decision.strip.empty?
+    end
+
+    private_class_method def self.validate_weight!(weight)
+      raise ValidationError, "Weight cannot be nil" if weight.nil?
+      raise ValidationError, "Weight must be a Numeric" unless weight.is_a?(Numeric)
+      raise ValidationError, "Weight must be between 0 and 1" unless weight.between?(0, 1)
+    end
+
+    private_class_method def self.validate_reason!(reason)
+      raise ValidationError, "Reason cannot be nil" if reason.nil?
+      raise ValidationError, "Reason must be a String" unless reason.is_a?(String)
+      raise ValidationError, "Reason cannot be empty" if reason.strip.empty?
+    end
+
+    private_class_method def self.validate_evaluator_name!(name)
+      raise ValidationError, "Evaluator name cannot be nil" if name.nil?
+      raise ValidationError, "Evaluator name must be a String or Symbol" unless name.is_a?(String) || name.is_a?(Symbol)
+    end
+
+    private_class_method def self.validate_frozen!(evaluation)
+      raise ValidationError, "Evaluation must be frozen for thread-safety (call .freeze)" unless evaluation.frozen?
+
+      # Verify nested structures are also frozen
+      raise ValidationError, "Evaluation decision must be frozen" unless evaluation.decision.frozen?
+
+      raise ValidationError, "Evaluation reason must be frozen" unless evaluation.reason.frozen?
+
+      raise ValidationError, "Evaluation evaluator_name must be frozen" unless evaluation.evaluator_name.frozen?
+
+      return unless evaluation.metadata && !evaluation.metadata.frozen?
+
+      raise ValidationError, "Evaluation metadata must be frozen"
+    end
+  end
+end

data/lib/decision_agent/evaluators/json_rule_evaluator.rb

@@ -10,6 +10,12 @@ module DecisionAgent
         @ruleset = Dsl::RuleParser.parse(@rules_json)
         @ruleset_name = @ruleset["ruleset"] || "unknown"
         @name = name || "JsonRuleEvaluator(#{@ruleset_name})"
+
+        # Freeze ruleset to ensure thread-safety
+        deep_freeze(@ruleset)
+        @rules_json.freeze
+        @ruleset_name.freeze
+        @name.freeze
       end
 
       def evaluate(context, feedback: {})
@@ -46,6 +52,26 @@ module DecisionAgent
           Dsl::ConditionEvaluator.evaluate(if_clause, context)
         end
       end
+
+      # Deep freeze helper method
+      def deep_freeze(obj)
+        case obj
+        when Hash
+          obj.each do |k, v|
+            deep_freeze(k)
+            deep_freeze(v)
+          end
+          obj.freeze
+        when Array
+          obj.each { |item| deep_freeze(item) }
+          obj.freeze
+        when String, Symbol, Numeric, TrueClass, FalseClass, NilClass
+          obj.freeze
+        else
+          obj.freeze if obj.respond_to?(:freeze)
+        end
+        obj
+      end
     end
   end
 end

data/lib/decision_agent/evaluators/static_evaluator.rb

@@ -11,12 +11,8 @@ module DecisionAgent
         @custom_metadata = metadata
       end
 
-      def evaluate(context, feedback: {})
-        metadata = if @custom_metadata
-          @custom_metadata
-        else
-          { type: "static" }
-        end
+      def evaluate(_context, feedback: {})
+        metadata = @custom_metadata || { type: "static" }
 
         Evaluation.new(
           decision: @decision,