decision_agent 0.1.1

data/bin/decision_agent

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require_relative "../lib/decision_agent"
+require_relative "../lib/decision_agent/web/server"
+
+def print_help
+  puts <<~HELP
+    DecisionAgent CLI
+
+    Usage:
+      decision_agent [command] [options]
+
+    Commands:
+      web [PORT]         Start the web UI rule builder (default port: 4567)
+      validate FILE      Validate a rules JSON file
+      version            Show version
+      help               Show this help message
+
+    Examples:
+      decision_agent web               # Start web UI on port 4567
+      decision_agent web 8080          # Start web UI on port 8080
+      decision_agent validate rules.json
+      decision_agent version
+
+    For more information, visit:
+    https://github.com/yourusername/decision_agent
+  HELP
+end
+
+def start_web_ui(port = 4567)
+  puts "🎯 Starting DecisionAgent Rule Builder..."
+  puts "📍 Server: http://localhost:#{port}"
+  puts "⚡️ Press Ctrl+C to stop"
+  puts ""
+
+  DecisionAgent::Web::Server.start!(port: port)
+end
+
+def validate_file(filepath)
+  unless File.exist?(filepath)
+    puts "❌ Error: File not found: #{filepath}"
+    exit 1
+  end
+
+  begin
+    puts "🔍 Validating #{filepath}..."
+
+    json_content = File.read(filepath)
+    data = JSON.parse(json_content)
+
+    DecisionAgent::Dsl::SchemaValidator.validate!(data)
+
+    puts "✅ Validation successful!"
+    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
+    puts "❌ Unexpected Error:"
+    puts "   #{e.message}"
+    exit 1
+  end
+end
+
+# Main CLI handler
+command = ARGV[0] || "help"
+
+case command
+when "web"
+  port = ARGV[1] ? ARGV[1].to_i : 4567
+  start_web_ui(port)
+
+when "validate"
+  if ARGV[1].nil?
+    puts "❌ Error: Please provide a file path"
+    puts "Usage: decision_agent validate FILE"
+    exit 1
+  end
+  validate_file(ARGV[1])
+
+when "version"
+  puts "DecisionAgent version #{DecisionAgent::VERSION}"
+
+when "help", "-h", "--help"
+  print_help
+
+else
+  puts "❌ Unknown command: #{command}"
+  puts ""
+  print_help
+  exit 1
+end

data/lib/decision_agent/agent.rb

@@ -0,0 +1,147 @@
+require "digest"
+require "json"
+
+module DecisionAgent
+  class Agent
+    attr_reader :evaluators, :scoring_strategy, :audit_adapter
+
+    def initialize(evaluators:, scoring_strategy: nil, audit_adapter: nil)
+      @evaluators = Array(evaluators)
+      @scoring_strategy = scoring_strategy || Scoring::WeightedAverage.new
+      @audit_adapter = audit_adapter || Audit::NullAdapter.new
+
+      validate_configuration!
+    end
+
+    def decide(context:, feedback: {})
+      ctx = context.is_a?(Context) ? context : Context.new(context)
+
+      evaluations = collect_evaluations(ctx, feedback)
+
+      raise NoEvaluationsError if evaluations.empty?
+
+      scored_result = @scoring_strategy.score(evaluations)
+
+      decision_value = scored_result[:decision]
+      confidence_value = scored_result[:confidence]
+
+      explanations = build_explanations(evaluations, decision_value, confidence_value)
+
+      audit_payload = build_audit_payload(
+        context: ctx,
+        evaluations: evaluations,
+        decision: decision_value,
+        confidence: confidence_value,
+        feedback: feedback
+      )
+
+      decision = Decision.new(
+        decision: decision_value,
+        confidence: confidence_value,
+        explanations: explanations,
+        evaluations: evaluations,
+        audit_payload: audit_payload
+      )
+
+      @audit_adapter.record(decision, ctx)
+
+      decision
+    end
+
+    private
+
+    def validate_configuration!
+      if @evaluators.empty?
+        raise InvalidConfigurationError, "At least one evaluator is required"
+      end
+
+      @evaluators.each do |evaluator|
+        unless evaluator.respond_to?(:evaluate)
+          raise InvalidEvaluatorError
+        end
+      end
+
+      unless @scoring_strategy.respond_to?(:score)
+        raise InvalidScoringStrategyError
+      end
+
+      unless @audit_adapter.respond_to?(:record)
+        raise InvalidAuditAdapterError
+      end
+    end
+
+    def collect_evaluations(context, feedback)
+      @evaluators.map do |evaluator|
+        begin
+          evaluator.evaluate(context, feedback: feedback)
+        rescue => e
+          nil
+        end
+      end.compact
+    end
+
+    def build_explanations(evaluations, final_decision, confidence)
+      explanations = []
+
+      matching_evals = evaluations.select { |e| e.decision == final_decision }
+
+      explanations << "Decision: #{final_decision} (confidence: #{confidence.round(2)})"
+
+      if matching_evals.size == 1
+        eval = matching_evals.first
+        explanations << "#{eval.evaluator_name}: #{eval.reason} (weight: #{eval.weight})"
+      elsif matching_evals.size > 1
+        explanations << "Based on #{matching_evals.size} evaluators:"
+        matching_evals.each do |eval|
+          explanations << "  - #{eval.evaluator_name}: #{eval.reason} (weight: #{eval.weight})"
+        end
+      end
+
+      conflicting_evals = evaluations.reject { |e| e.decision == final_decision }
+      if conflicting_evals.any?
+        explanations << "Conflicting evaluations resolved by #{@scoring_strategy.class.name.split('::').last}:"
+        conflicting_evals.each do |eval|
+          explanations << "  - #{eval.evaluator_name}: suggested '#{eval.decision}' (weight: #{eval.weight})"
+        end
+      end
+
+      explanations
+    end
+
+    def build_audit_payload(context:, evaluations:, decision:, confidence:, feedback:)
+      timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ")
+
+      payload = {
+        timestamp: timestamp,
+        context: context.to_h,
+        feedback: feedback,
+        evaluations: evaluations.map(&:to_h),
+        decision: decision,
+        confidence: confidence,
+        scoring_strategy: @scoring_strategy.class.name,
+        agent_version: DecisionAgent::VERSION
+      }
+
+      payload[:deterministic_hash] = compute_deterministic_hash(payload)
+      payload
+    end
+
+    def compute_deterministic_hash(payload)
+      hashable = payload.slice(:context, :evaluations, :decision, :confidence, :scoring_strategy)
+      canonical = canonical_json(hashable)
+      Digest::SHA256.hexdigest(canonical)
+    end
+
+    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
+    end
+  end
+end

data/lib/decision_agent/audit/adapter.rb

@@ -0,0 +1,9 @@
+module DecisionAgent
+  module Audit
+    class Adapter
+      def record(decision, context)
+        raise NotImplementedError, "Subclasses must implement #record"
+      end
+    end
+  end
+end

data/lib/decision_agent/audit/logger_adapter.rb

@@ -0,0 +1,27 @@
+require "logger"
+require "json"
+
+module DecisionAgent
+  module Audit
+    class LoggerAdapter < Adapter
+      attr_reader :logger
+
+      def initialize(logger: nil, level: Logger::INFO)
+        @logger = logger || Logger.new($stdout)
+        @logger.level = level
+      end
+
+      def record(decision, context)
+        log_entry = {
+          timestamp: decision.audit_payload[:timestamp],
+          decision: decision.decision,
+          confidence: decision.confidence,
+          context: context.to_h,
+          audit_hash: decision.audit_payload[:deterministic_hash]
+        }
+
+        @logger.info(JSON.generate(log_entry))
+      end
+    end
+  end
+end

data/lib/decision_agent/audit/null_adapter.rb

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

data/lib/decision_agent/context.rb

@@ -0,0 +1,42 @@
+module DecisionAgent
+  class Context
+    attr_reader :data
+
+    def initialize(data)
+      @data = deep_freeze(data.is_a?(Hash) ? data : {})
+    end
+
+    def [](key)
+      @data[key]
+    end
+
+    def fetch(key, default = nil)
+      @data.fetch(key, default)
+    end
+
+    def key?(key)
+      @data.key?(key)
+    end
+
+    def to_h
+      @data
+    end
+
+    def ==(other)
+      other.is_a?(Context) && @data == other.data
+    end
+
+    private
+
+    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/decision.rb

@@ -0,0 +1,51 @@
+module DecisionAgent
+  class Decision
+    attr_reader :decision, :confidence, :explanations, :evaluations, :audit_payload
+
+    def initialize(decision:, confidence:, explanations:, evaluations:, audit_payload:)
+      validate_confidence!(confidence)
+
+      @decision = decision.to_s.freeze
+      @confidence = confidence.to_f
+      @explanations = Array(explanations).map(&:freeze).freeze
+      @evaluations = Array(evaluations).freeze
+      @audit_payload = deep_freeze(audit_payload)
+    end
+
+    def to_h
+      {
+        decision: @decision,
+        confidence: @confidence,
+        explanations: @explanations,
+        evaluations: @evaluations.map(&:to_h),
+        audit_payload: @audit_payload
+      }
+    end
+
+    def ==(other)
+      other.is_a?(Decision) &&
+        @decision == other.decision &&
+        (@confidence - other.confidence).abs < 0.0001 &&
+        @explanations == other.explanations &&
+        @evaluations == other.evaluations
+    end
+
+    private
+
+    def validate_confidence!(confidence)
+      c = confidence.to_f
+      raise InvalidConfidenceError.new(confidence) unless c >= 0.0 && c <= 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/dsl/condition_evaluator.rb

@@ -0,0 +1,133 @@
+module DecisionAgent
+  module Dsl
+    # Evaluates conditions in the rule DSL against a context
+    #
+    # Supports:
+    # - Field conditions with various operators
+    # - Nested field access via dot notation (e.g., "user.profile.role")
+    # - Logical operators (all/any)
+    class ConditionEvaluator
+      def self.evaluate(condition, context)
+        return false unless condition.is_a?(Hash)
+
+        if condition.key?("all")
+          evaluate_all(condition["all"], context)
+        elsif condition.key?("any")
+          evaluate_any(condition["any"], context)
+        elsif condition.key?("field")
+          evaluate_field_condition(condition, context)
+        else
+          false
+        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
+
+      # Evaluates 'any' condition - returns true if AT LEAST ONE sub-condition is true
+      # 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
+
+      def self.evaluate_field_condition(condition, context)
+        field = condition["field"]
+        op = condition["op"]
+        expected_value = condition["value"]
+
+        actual_value = get_nested_value(context.to_h, field)
+
+        case op
+        when "eq"
+          # Equality - uses Ruby's == for comparison
+          actual_value == expected_value
+
+        when "neq"
+          # Not equal - inverse of ==
+          actual_value != expected_value
+
+        when "gt"
+          # Greater than - only for comparable types (numbers, strings)
+          comparable?(actual_value, expected_value) && actual_value > expected_value
+
+        when "gte"
+          # Greater than or equal - only for comparable types
+          comparable?(actual_value, expected_value) && actual_value >= expected_value
+
+        when "lt"
+          # Less than - only for comparable types
+          comparable?(actual_value, expected_value) && actual_value < expected_value
+
+        when "lte"
+          # Less than or equal - only for comparable types
+          comparable?(actual_value, expected_value) && actual_value <= expected_value
+
+        when "in"
+          # Array membership - checks if actual_value is in the expected array
+          Array(expected_value).include?(actual_value)
+
+        when "present"
+          # PRESENT SEMANTICS:
+          # Returns true if value exists AND is not empty
+          # - nil: false
+          # - Empty string "": false
+          # - Empty array []: false
+          # - Empty hash {}: false
+          # - Zero 0: true (zero is a valid value)
+          # - False boolean: true (false is a valid value)
+          # - Non-empty values: true
+          !actual_value.nil? && (actual_value.respond_to?(:empty?) ? !actual_value.empty? : true)
+
+        when "blank"
+          # BLANK SEMANTICS:
+          # Returns true if value is nil OR empty
+          # - nil: true
+          # - Empty string "": true
+          # - Empty array []: true
+          # - Empty hash {}: true
+          # - Zero 0: false (zero is a valid value)
+          # - False boolean: false (false is a valid value)
+          # - Non-empty values: false
+          actual_value.nil? || (actual_value.respond_to?(:empty?) ? actual_value.empty? : false)
+
+        else
+          # Unknown operator - returns false (fail-safe)
+          # Note: Validation should catch this earlier
+          false
+        end
+      end
+
+      # Retrieves nested values from a hash using dot notation
+      #
+      # Examples:
+      #   get_nested_value({user: {role: "admin"}}, "user.role") # => "admin"
+      #   get_nested_value({user: {role: "admin"}}, "user.missing") # => nil
+      #   get_nested_value({user: nil}, "user.role") # => nil
+      #
+      # Supports both string and symbol keys in the hash
+      def self.get_nested_value(hash, key_path)
+        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
+
+      # Checks if two values can be compared with <, >, <=, >=
+      # Only allows comparison between values of the same type
+      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
+      end
+    end
+  end
+end

data/lib/decision_agent/dsl/rule_parser.rb

@@ -0,0 +1,36 @@
+require "json"
+
+module DecisionAgent
+  module Dsl
+    class RuleParser
+      def self.parse(json_string)
+        data = parse_json(json_string)
+
+        # Use comprehensive schema validator
+        SchemaValidator.validate!(data)
+
+        data
+      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"
+      end
+
+      private
+
+      def self.parse_json(input)
+        if input.is_a?(String)
+          JSON.parse(input)
+        elsif input.is_a?(Hash)
+          # Already parsed, convert to string keys for consistency
+          JSON.parse(JSON.generate(input))
+        else
+          raise InvalidRuleDslError, "Expected JSON string or Hash, got #{input.class}"
+        end
+      end
+    end
+  end
+end