decision_agent 0.1.2 → 0.1.3

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
 
@@ -62,13 +62,16 @@ module DecisionAgent
 
   class NotFoundError < Error
     def initialize(message = "Resource not found")
-      super(message)
+      super
     end
   end
 
   class ValidationError < Error
     def initialize(message = "Validation failed")
-      super(message)
+      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,

data/lib/decision_agent/monitoring/alert_manager.rb

@@ -0,0 +1,282 @@
+require "monitor"
+
+module DecisionAgent
+  module Monitoring
+    # Alert manager for anomaly detection and notifications
+    class AlertManager
+      include MonitorMixin
+
+      attr_reader :rules, :alerts
+
+      def initialize(metrics_collector:)
+        super()
+        @metrics_collector = metrics_collector
+        @rules = []
+        @alerts = []
+        @alert_handlers = []
+        @check_interval = 60 # seconds
+        @monitoring_thread = nil
+        freeze_config
+      end
+
+      # Define an alert rule
+      def add_rule(name:, condition:, severity: :warning, threshold: nil, message: nil, cooldown: 300)
+        synchronize do
+          rule = {
+            id: generate_rule_id(name),
+            name: name,
+            condition: condition,
+            severity: severity,
+            threshold: threshold,
+            message: message || "Alert: #{name}",
+            cooldown: cooldown,
+            last_triggered: nil,
+            enabled: true
+          }
+
+          @rules << rule
+          rule
+        end
+      end
+
+      # Remove a rule
+      def remove_rule(rule_id)
+        synchronize do
+          @rules.reject! { |r| r[:id] == rule_id }
+        end
+      end
+
+      # Enable/disable rule
+      def toggle_rule(rule_id, enabled)
+        synchronize do
+          rule = @rules.find { |r| r[:id] == rule_id }
+          rule[:enabled] = enabled if rule
+        end
+      end
+
+      # Register alert handler
+      def add_handler(&block)
+        synchronize do
+          @alert_handlers << block
+        end
+      end
+
+      # Start monitoring
+      def start_monitoring(interval: 60)
+        synchronize do
+          return if @monitoring_thread&.alive?
+
+          @check_interval = interval
+          @monitoring_thread = Thread.new do
+            loop do
+              check_rules
+              sleep @check_interval
+            rescue StandardError => e
+              warn "Alert monitoring error: #{e.message}"
+            end
+          end
+        end
+      end
+
+      # Stop monitoring
+      def stop_monitoring
+        synchronize do
+          @monitoring_thread&.kill
+          @monitoring_thread = nil
+        end
+      end
+
+      # Manually check all rules
+      def check_rules
+        stats = @metrics_collector.statistics
+
+        @rules.each do |rule|
+          next unless rule[:enabled]
+          next if in_cooldown?(rule)
+
+          trigger_alert(rule, stats) if evaluate_condition(rule[:condition], stats)
+        end
+      end
+
+      # Get active alerts
+      def active_alerts
+        synchronize do
+          @alerts.select { |a| a[:status] == :active }
+        end
+      end
+
+      # Get all alerts
+      def all_alerts(limit: 100)
+        synchronize do
+          @alerts.last(limit)
+        end
+      end
+
+      # Acknowledge alert
+      def acknowledge_alert(alert_id, acknowledged_by: "system")
+        synchronize do
+          alert = @alerts.find { |a| a[:id] == alert_id }
+          if alert
+            alert[:status] = :acknowledged
+            alert[:acknowledged_by] = acknowledged_by
+            alert[:acknowledged_at] = Time.now.utc
+          end
+        end
+      end
+
+      # Resolve alert
+      def resolve_alert(alert_id, resolved_by: "system")
+        synchronize do
+          alert = @alerts.find { |a| a[:id] == alert_id }
+          if alert
+            alert[:status] = :resolved
+            alert[:resolved_by] = resolved_by
+            alert[:resolved_at] = Time.now.utc
+          end
+        end
+      end
+
+      # Clear old alerts
+      def clear_old_alerts(older_than: 86_400)
+        synchronize do
+          cutoff = Time.now.utc - older_than
+          @alerts.reject! { |a| a[:triggered_at] < cutoff && a[:status] != :active }
+        end
+      end
+
+      # Built-in alert conditions
+      def self.high_error_rate(threshold: 0.1)
+        lambda do |stats|
+          total_ops = stats.dig(:performance, :total_operations) || 0
+          return false if total_ops.zero?
+
+          success_rate = stats.dig(:performance, :success_rate) || 1.0
+          (1.0 - success_rate) > threshold
+        end
+      end
+
+      def self.low_confidence(threshold: 0.5)
+        lambda do |stats|
+          avg_confidence = stats.dig(:decisions, :avg_confidence)
+          avg_confidence && avg_confidence < threshold
+        end
+      end
+
+      def self.high_latency(threshold_ms: 1000)
+        lambda do |stats|
+          p95 = stats.dig(:performance, :p95_duration_ms)
+          p95 && p95 > threshold_ms
+        end
+      end
+
+      def self.error_spike(threshold: 10, time_window: 300)
+        lambda do |stats|
+          recent_errors = stats.dig(:errors, :total) || 0
+          recent_errors > threshold
+        end
+      end
+
+      def self.decision_anomaly(expected_rate: 100, variance: 0.3)
+        lambda do |stats|
+          total = stats.dig(:decisions, :total) || 0
+          time_range = stats.dig(:summary, :time_range)
+
+          # Simple anomaly detection based on rate
+          return false unless time_range
+
+          lower_bound = expected_rate * (1 - variance)
+          upper_bound = expected_rate * (1 + variance)
+
+          total < lower_bound || total > upper_bound
+        end
+      end
+
+      private
+
+      def freeze_config
+        # No immutable config to freeze yet
+      end
+
+      def generate_rule_id(name)
+        "#{sanitize_name(name)}_#{Time.now.to_i}_#{rand(1000)}"
+      end
+
+      def sanitize_name(name)
+        name.to_s.downcase.gsub(/[^a-z0-9]/, "_")
+      end
+
+      def in_cooldown?(rule)
+        return false unless rule[:last_triggered]
+
+        Time.now.utc - rule[:last_triggered] < rule[:cooldown]
+      end
+
+      def evaluate_condition(condition, stats)
+        case condition
+        when Proc
+          condition.call(stats)
+        when Hash
+          evaluate_hash_condition(condition, stats)
+        else
+          false
+        end
+      end
+
+      def evaluate_hash_condition(condition, stats)
+        # Support simple hash-based conditions
+        # Example: { metric: "decisions.avg_confidence", op: "lt", value: 0.5 }
+        metric_path = condition[:metric]&.split(".")
+        return false unless metric_path
+
+        value = stats.dig(*metric_path.map(&:to_sym))
+        return false if value.nil?
+
+        case condition[:op]
+        when "gt", ">"
+          value > condition[:value]
+        when "lt", "<"
+          value < condition[:value]
+        when "eq", "=="
+          value == condition[:value]
+        when "gte", ">="
+          value >= condition[:value]
+        when "lte", "<="
+          value <= condition[:value]
+        else
+          false
+        end
+      end
+
+      def trigger_alert(rule, stats)
+        alert = {
+          id: "alert_#{Time.now.to_i}_#{rand(10_000)}",
+          rule_id: rule[:id],
+          rule_name: rule[:name],
+          severity: rule[:severity],
+          message: rule[:message],
+          triggered_at: Time.now.utc,
+          status: :active,
+          context: {
+            stats_snapshot: stats
+          }
+        }
+
+        @alerts << alert
+        rule[:last_triggered] = Time.now.utc
+
+        # Notify handlers
+        notify_handlers(alert)
+
+        alert
+      end
+
+      def notify_handlers(alert)
+        @alert_handlers.each do |handler|
+          handler.call(alert)
+        rescue StandardError => e
+          warn "Alert handler failed: #{e.message}"
+        end
+      end
+    end
+  end
+end