decision_agent 0.1.1

data/lib/decision_agent/dsl/schema_validator.rb

@@ -0,0 +1,275 @@
+module DecisionAgent
+  module Dsl
+    # JSON Schema validator for Decision Agent rule DSL
+    # Provides comprehensive validation with detailed error messages
+    class SchemaValidator
+      SUPPORTED_OPERATORS = %w[eq neq gt gte lt lte in present blank].freeze
+
+      CONDITION_TYPES = %w[all any field].freeze
+
+      # Validates the entire ruleset structure
+      def self.validate!(data)
+        new(data).validate!
+      end
+
+      def initialize(data)
+        @data = data
+        @errors = []
+      end
+
+      def validate!
+        validate_root_structure
+        validate_version
+        validate_rules_array
+        validate_each_rule
+
+        raise InvalidRuleDslError, format_errors if @errors.any?
+
+        true
+      end
+
+      private
+
+      def validate_root_structure
+        unless @data.is_a?(Hash)
+          @errors << "Root element must be a hash/object, got #{@data.class}"
+          return
+        end
+      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
+      end
+
+      def validate_rules_array
+        return if @errors.any?
+
+        rules = @data["rules"] || @data[:rules]
+
+        unless rules
+          @errors << "Missing required field 'rules'. Expected an array of rule objects."
+          return
+        end
+
+        unless rules.is_a?(Array)
+          @errors << "Field 'rules' must be an array, got #{rules.class}. Example: \"rules\": [...]"
+        end
+      end
+
+      def validate_each_rule
+        return if @errors.any?
+
+        rules = @data["rules"] || @data[:rules]
+        return unless rules.is_a?(Array)
+
+        rules.each_with_index do |rule, idx|
+          validate_rule(rule, idx)
+        end
+      end
+
+      def validate_rule(rule, idx)
+        rule_path = "rules[#{idx}]"
+
+        unless rule.is_a?(Hash)
+          @errors << "#{rule_path}: Rule must be a hash/object, got #{rule.class}"
+          return
+        end
+
+        # Validate required fields
+        validate_rule_id(rule, rule_path)
+        validate_if_clause(rule, rule_path)
+        validate_then_clause(rule, rule_path)
+      end
+
+      def validate_rule_id(rule, rule_path)
+        rule_id = rule["id"] || rule[:id]
+
+        unless rule_id
+          @errors << "#{rule_path}: Missing required field 'id'. Each rule must have a unique identifier."
+          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
+      end
+
+      def validate_if_clause(rule, rule_path)
+        if_clause = rule["if"] || rule[:if]
+
+        unless if_clause
+          @errors << "#{rule_path}: Missing required field 'if'. " \
+                     "Expected a condition object with 'field', 'all', or 'any'."
+          return
+        end
+
+        validate_condition(if_clause, "#{rule_path}.if")
+      end
+
+      def validate_condition(condition, path)
+        unless condition.is_a?(Hash)
+          @errors << "#{path}: Condition must be a hash/object, got #{condition.class}"
+          return
+        end
+
+        condition_type = detect_condition_type(condition)
+
+        unless condition_type
+          @errors << "#{path}: Condition must have one of: 'field', 'all', or 'any'. " \
+                     "Example: { \"field\": \"status\", \"op\": \"eq\", \"value\": \"active\" }"
+          return
+        end
+
+        case condition_type
+        when "field"
+          validate_field_condition(condition, path)
+        when "all"
+          validate_all_condition(condition, path)
+        when "any"
+          validate_any_condition(condition, path)
+        end
+      end
+
+      def detect_condition_type(condition)
+        if condition.key?("field") || condition.key?(:field)
+          "field"
+        elsif condition.key?("all") || condition.key?(:all)
+          "all"
+        elsif condition.key?("any") || condition.key?(:any)
+          "any"
+        end
+      end
+
+      def validate_field_condition(condition, path)
+        field = condition["field"] || condition[:field]
+        operator = condition["op"] || condition[:op]
+        value = condition["value"] || condition[:value]
+
+        # Validate field
+        unless field
+          @errors << "#{path}: Field condition missing 'field' key"
+        end
+
+        # Validate operator
+        unless operator
+          @errors << "#{path}: Field condition missing 'op' (operator) key"
+          return
+        end
+
+        validate_operator(operator, path)
+
+        # Validate value (not required for 'present' and 'blank')
+        if !%w[present blank].include?(operator.to_s) && value.nil?
+          @errors << "#{path}: Field condition missing 'value' key for operator '#{operator}'"
+        end
+
+        # Validate dot-notation in field path
+        validate_field_path(field, path) if field
+      end
+
+      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
+      end
+
+      def validate_field_path(field, path)
+        return unless field.is_a?(String)
+
+        if field.empty?
+          @errors << "#{path}: Field path cannot be empty"
+          return
+        end
+
+        # 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
+      end
+
+      def validate_all_condition(condition, path)
+        sub_conditions = condition["all"] || condition[:all]
+
+        unless sub_conditions.is_a?(Array)
+          @errors << "#{path}: 'all' condition must contain an array of conditions, got #{sub_conditions.class}"
+          return
+        end
+
+        sub_conditions.each_with_index do |sub_cond, idx|
+          validate_condition(sub_cond, "#{path}.all[#{idx}]")
+        end
+      end
+
+      def validate_any_condition(condition, path)
+        sub_conditions = condition["any"] || condition[:any]
+
+        unless sub_conditions.is_a?(Array)
+          @errors << "#{path}: 'any' condition must contain an array of conditions, got #{sub_conditions.class}"
+          return
+        end
+
+        sub_conditions.each_with_index do |sub_cond, idx|
+          validate_condition(sub_cond, "#{path}.any[#{idx}]")
+        end
+      end
+
+      def validate_then_clause(rule, rule_path)
+        then_clause = rule["then"] || rule[:then]
+
+        unless then_clause
+          @errors << "#{rule_path}: Missing required field 'then'. " \
+                     "Expected an object with 'decision' field."
+          return
+        end
+
+        unless then_clause.is_a?(Hash)
+          @errors << "#{rule_path}.then: Must be a hash/object, got #{then_clause.class}"
+          return
+        end
+
+        # Validate decision
+        decision = then_clause["decision"] || then_clause[:decision]
+
+        unless decision
+          @errors << "#{rule_path}.then: Missing required field 'decision'"
+        end
+
+        # Validate optional weight
+        weight = then_clause["weight"] || then_clause[:weight]
+
+        if weight && !weight.is_a?(Numeric)
+          @errors << "#{rule_path}.then.weight: Must be a number, got #{weight.class}"
+        elsif weight && (weight < 0.0 || weight > 1.0)
+          @errors << "#{rule_path}.then.weight: Must be between 0.0 and 1.0, got #{weight}"
+        end
+
+        # 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
+      end
+
+      def format_errors
+        header = "Rule DSL validation failed with #{@errors.size} error#{'s' if @errors.size > 1}:\n\n"
+        numbered_errors = @errors.map.with_index { |err, idx| "  #{idx + 1}. #{err}" }.join("\n")
+
+        footer = "\n\nFor documentation on the rule DSL format, see the README."
+
+        header + numbered_errors + footer
+      end
+    end
+  end
+end

data/lib/decision_agent/errors.rb

@@ -0,0 +1,62 @@
+module DecisionAgent
+  class Error < StandardError; end
+
+  class InvalidRuleDslError < Error
+    def initialize(message = "Invalid rule DSL structure")
+      super(message)
+    end
+  end
+
+  class NoEvaluationsError < Error
+    def initialize(message = "No evaluators returned a decision")
+      super(message)
+    end
+  end
+
+  class ReplayMismatchError < Error
+    attr_reader :expected, :actual, :differences
+
+    def initialize(expected:, actual:, differences:)
+      @expected = expected
+      @actual = actual
+      @differences = differences
+      super("Replay mismatch detected: #{differences.join(', ')}")
+    end
+  end
+
+  class InvalidConfigurationError < Error
+    def initialize(message = "Invalid agent configuration")
+      super(message)
+    end
+  end
+
+  class InvalidEvaluatorError < Error
+    def initialize(message = "Evaluator must respond to #evaluate")
+      super(message)
+    end
+  end
+
+  class InvalidScoringStrategyError < Error
+    def initialize(message = "Scoring strategy must respond to #score")
+      super(message)
+    end
+  end
+
+  class InvalidAuditAdapterError < Error
+    def initialize(message = "Audit adapter must respond to #record")
+      super(message)
+    end
+  end
+
+  class InvalidConfidenceError < Error
+    def initialize(confidence)
+      super("Confidence must be between 0.0 and 1.0, got: #{confidence}")
+    end
+  end
+
+  class InvalidWeightError < Error
+    def initialize(weight)
+      super("Weight must be between 0.0 and 1.0, got: #{weight}")
+    end
+  end
+end

data/lib/decision_agent/evaluation.rb

@@ -0,0 +1,52 @@
+module DecisionAgent
+  class Evaluation
+    attr_reader :decision, :weight, :reason, :evaluator_name, :metadata
+
+    def initialize(decision:, weight:, reason:, evaluator_name:, metadata: {})
+      validate_weight!(weight)
+
+      @decision = decision.to_s.freeze
+      @weight = weight.to_f
+      @reason = reason.to_s.freeze
+      @evaluator_name = evaluator_name.to_s.freeze
+      @metadata = deep_freeze(metadata)
+    end
+
+    def to_h
+      {
+        decision: @decision,
+        weight: @weight,
+        reason: @reason,
+        evaluator_name: @evaluator_name,
+        metadata: @metadata
+      }
+    end
+
+    def ==(other)
+      other.is_a?(Evaluation) &&
+        @decision == other.decision &&
+        @weight == other.weight &&
+        @reason == other.reason &&
+        @evaluator_name == other.evaluator_name &&
+        @metadata == other.metadata
+    end
+
+    private
+
+    def validate_weight!(weight)
+      w = weight.to_f
+      raise InvalidWeightError.new(weight) unless w >= 0.0 && w <= 1.0
+    end
+
+    def deep_freeze(obj)
+      case obj
+      when Hash
+        obj.transform_values { |v| deep_freeze(v) }.freeze
+      when Array
+        obj.map { |v| deep_freeze(v) }.freeze
+      else
+        obj.freeze
+      end
+    end
+  end
+end

data/lib/decision_agent/evaluators/base.rb

@@ -0,0 +1,15 @@
+module DecisionAgent
+  module Evaluators
+    class Base
+      def evaluate(context, feedback: {})
+        raise NotImplementedError, "Subclasses must implement #evaluate"
+      end
+
+      protected
+
+      def evaluator_name
+        self.class.name.split("::").last
+      end
+    end
+  end
+end

data/lib/decision_agent/evaluators/json_rule_evaluator.rb

@@ -0,0 +1,51 @@
+require "json"
+
+module DecisionAgent
+  module Evaluators
+    class JsonRuleEvaluator < Base
+      attr_reader :ruleset_name
+
+      def initialize(rules_json:, name: nil)
+        @rules_json = rules_json.is_a?(String) ? rules_json : JSON.generate(rules_json)
+        @ruleset = Dsl::RuleParser.parse(@rules_json)
+        @ruleset_name = @ruleset["ruleset"] || "unknown"
+        @name = name || "JsonRuleEvaluator(#{@ruleset_name})"
+      end
+
+      def evaluate(context, feedback: {})
+        ctx = context.is_a?(Context) ? context : Context.new(context)
+
+        matched_rule = find_first_matching_rule(ctx)
+
+        return nil unless matched_rule
+
+        then_clause = matched_rule["then"]
+
+        Evaluation.new(
+          decision: then_clause["decision"],
+          weight: then_clause["weight"] || 1.0,
+          reason: then_clause["reason"] || "Rule matched",
+          evaluator_name: @name,
+          metadata: {
+            type: "json_rule",
+            rule_id: matched_rule["id"],
+            ruleset: @ruleset_name
+          }
+        )
+      end
+
+      private
+
+      def find_first_matching_rule(context)
+        rules = @ruleset["rules"] || []
+
+        rules.find do |rule|
+          if_clause = rule["if"]
+          next false unless if_clause
+
+          Dsl::ConditionEvaluator.evaluate(if_clause, context)
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/evaluators/static_evaluator.rb

@@ -0,0 +1,31 @@
+module DecisionAgent
+  module Evaluators
+    class StaticEvaluator < Base
+      attr_reader :decision, :weight, :reason, :name, :custom_metadata
+
+      def initialize(decision:, weight: 1.0, reason: "Static decision", name: nil, metadata: nil)
+        @decision = decision
+        @weight = weight.to_f
+        @reason = reason
+        @name = name || evaluator_name
+        @custom_metadata = metadata
+      end
+
+      def evaluate(context, feedback: {})
+        metadata = if @custom_metadata
+          @custom_metadata
+        else
+          { type: "static" }
+        end
+
+        Evaluation.new(
+          decision: @decision,
+          weight: @weight,
+          reason: @reason,
+          evaluator_name: @name,
+          metadata: metadata
+        )
+      end
+    end
+  end
+end

data/lib/decision_agent/replay/replay.rb

@@ -0,0 +1,147 @@
+require "digest"
+require "json"
+
+module DecisionAgent
+  module Replay
+    def self.run(audit_payload, strict: true)
+      validate_payload!(audit_payload)
+
+      context = Context.new(audit_payload[:context] || audit_payload["context"])
+      feedback = audit_payload[:feedback] || audit_payload["feedback"] || {}
+
+      original_evaluations = parse_evaluations(audit_payload)
+      original_decision = audit_payload[:decision] || audit_payload["decision"]
+      original_confidence = audit_payload[:confidence] || audit_payload["confidence"]
+
+      scoring_strategy = instantiate_scoring_strategy(audit_payload)
+
+      agent = Agent.new(
+        evaluators: build_replay_evaluators(original_evaluations),
+        scoring_strategy: scoring_strategy,
+        audit_adapter: Audit::NullAdapter.new
+      )
+
+      replayed_result = agent.decide(context: context, feedback: feedback)
+
+      if strict
+        validate_strict_match!(
+          original_decision: original_decision,
+          original_confidence: original_confidence,
+          replayed_decision: replayed_result.decision,
+          replayed_confidence: replayed_result.confidence
+        )
+      else
+        log_differences(
+          original_decision: original_decision,
+          original_confidence: original_confidence,
+          replayed_decision: replayed_result.decision,
+          replayed_confidence: replayed_result.confidence
+        )
+      end
+
+      replayed_result
+    end
+
+    private
+
+    def self.validate_payload!(payload)
+      required_keys = ["context", "evaluations", "decision", "confidence"]
+
+      required_keys.each do |key|
+        unless payload.key?(key) || payload.key?(key.to_sym)
+          raise InvalidRuleDslError, "Audit payload missing required key: #{key}"
+        end
+      end
+    end
+
+    def self.parse_evaluations(payload)
+      evals = payload[:evaluations] || payload["evaluations"]
+
+      evals.map do |eval_data|
+        if eval_data.is_a?(Evaluation)
+          eval_data
+        else
+          Evaluation.new(
+            decision: eval_data[:decision] || eval_data["decision"],
+            weight: eval_data[:weight] || eval_data["weight"],
+            reason: eval_data[:reason] || eval_data["reason"],
+            evaluator_name: eval_data[:evaluator_name] || eval_data["evaluator_name"],
+            metadata: eval_data[:metadata] || eval_data["metadata"] || {}
+          )
+        end
+      end
+    end
+
+    def self.build_replay_evaluators(evaluations)
+      evaluations.map do |evaluation|
+        Evaluators::StaticEvaluator.new(
+          decision: evaluation.decision,
+          weight: evaluation.weight,
+          reason: evaluation.reason,
+          name: evaluation.evaluator_name,
+          metadata: evaluation.metadata
+        )
+      end
+    end
+
+    def self.instantiate_scoring_strategy(payload)
+      strategy_name = payload[:scoring_strategy] || payload["scoring_strategy"]
+
+      return Scoring::WeightedAverage.new unless strategy_name
+
+      case strategy_name
+      when /WeightedAverage/
+        Scoring::WeightedAverage.new
+      when /MaxWeight/
+        Scoring::MaxWeight.new
+      when /Consensus/
+        Scoring::Consensus.new
+      when /Threshold/
+        Scoring::Threshold.new
+      else
+        Scoring::WeightedAverage.new
+      end
+    end
+
+    def self.validate_strict_match!(original_decision:, original_confidence:, replayed_decision:, replayed_confidence:)
+      differences = []
+
+      if original_decision.to_s != replayed_decision.to_s
+        differences << "decision mismatch (expected: #{original_decision}, got: #{replayed_decision})"
+      end
+
+      conf_diff = (original_confidence.to_f - replayed_confidence.to_f).abs
+      if conf_diff > 0.0001
+        differences << "confidence mismatch (expected: #{original_confidence}, got: #{replayed_confidence})"
+      end
+
+      if differences.any?
+        raise ReplayMismatchError.new(
+          expected: { decision: original_decision, confidence: original_confidence },
+          actual: { decision: replayed_decision, confidence: replayed_confidence },
+          differences: differences
+        )
+      end
+    end
+
+    def self.log_differences(original_decision:, original_confidence:, replayed_decision:, replayed_confidence:)
+      differences = []
+
+      if original_decision.to_s != replayed_decision.to_s
+        differences << "Decision changed: #{original_decision} -> #{replayed_decision}"
+      end
+
+      conf_diff = (original_confidence.to_f - replayed_confidence.to_f).abs
+      if conf_diff > 0.0001
+        differences << "Confidence changed: #{original_confidence} -> #{replayed_confidence}"
+      end
+
+      if differences.any?
+        warn "[DecisionAgent::Replay] Non-strict mode differences detected:"
+        differences.each { |diff| warn "  - #{diff}" }
+      end
+
+      differences
+    end
+  end
+end

data/lib/decision_agent/scoring/base.rb

@@ -0,0 +1,19 @@
+module DecisionAgent
+  module Scoring
+    class Base
+      def score(evaluations)
+        raise NotImplementedError, "Subclasses must implement #score"
+      end
+
+      protected
+
+      def normalize_confidence(value)
+        [[value, 0.0].max, 1.0].min
+      end
+
+      def round_confidence(value)
+        (value * 10000).round / 10000.0
+      end
+    end
+  end
+end

data/lib/decision_agent/scoring/consensus.rb

@@ -0,0 +1,40 @@
+module DecisionAgent
+  module Scoring
+    class Consensus < Base
+      attr_reader :minimum_agreement
+
+      def initialize(minimum_agreement: 0.5)
+        @minimum_agreement = minimum_agreement.to_f
+      end
+
+      def score(evaluations)
+        return { decision: nil, confidence: 0.0 } if evaluations.empty?
+
+        grouped = evaluations.group_by(&:decision)
+        total_count = evaluations.size
+
+        candidates = grouped.map do |decision, evals|
+          agreement = evals.size.to_f / total_count
+          avg_weight = evals.sum(&:weight) / evals.size
+
+          [decision, agreement, avg_weight]
+        end
+
+        candidates.sort_by! { |_, agreement, weight| [-agreement, -weight] }
+
+        winning_decision, agreement, avg_weight = candidates.first
+
+        if agreement >= @minimum_agreement
+          confidence = agreement * avg_weight
+        else
+          confidence = agreement * avg_weight * 0.5
+        end
+
+        {
+          decision: winning_decision,
+          confidence: round_confidence(normalize_confidence(confidence))
+        }
+      end
+    end
+  end
+end