DecisionAgent

A production-grade, deterministic, explainable, and auditable decision engine for Ruby.

Built for regulated domains. Deterministic by design. AI-optional.

• ✅ Deterministic - Same input always produces same output
• ✅ Explainable - Every decision includes human-readable reasoning
• ✅ Auditable - Reproduce any historical decision exactly
• ✅ Framework-agnostic - Pure Ruby, works anywhere
• ✅ Production-ready - Comprehensive testing, error handling, and versioning

gem install decision_agent

Or add to your Gemfile:

gem 'decision_agent'

require 'decision_agent'

# Define evaluator with business rules
evaluator = DecisionAgent::Evaluators::JsonRuleEvaluator.new(
  rules_json: {
    version: "1.0",
    ruleset: "approval_rules",
    rules: [{
      id: "high_value",
      if: { field: "amount", op: "gt", value: 1000 },
      then: { decision: "approve", weight: 0.9, reason: "High value transaction" }
    }]
  }
)

# Create decision agent
agent = DecisionAgent::Agent.new(evaluators: [evaluator])

# Make decision
result = agent.decide(context: { amount: 1500 })

puts result.decision      # => "approve"
puts result.confidence    # => 0.9
puts result.explanations  # => ["High value transaction"]

Launch the visual rule builder for non-technical users:

decision_agent web

Open http://localhost:4567 in your browser.

• Multiple Evaluators - Combine rule-based, ML, and custom logic
• Conflict Resolution - Weighted average, consensus, threshold, max weight
• Rich Context - Nested data, dot notation, flexible operators

• Complete Audit Trails - Every decision fully logged
• Deterministic Replay - Reproduce historical decisions exactly
• Compliance Ready - HIPAA, SOX, regulatory compliance support

• Pluggable Architecture - Custom evaluators, scoring, audit adapters
• Framework Agnostic - Works with Rails, Sinatra, or standalone
• JSON Rule DSL - Non-technical users can write rules
• Visual Rule Builder - Web UI for rule management

• Comprehensive Testing - 90%+ code coverage
• Error Handling - Clear, actionable error messages
• Versioning - Full rule version control and rollback
• Performance - Fast, zero external dependencies
• Thread-Safe - Safe for multi-threaded servers and background jobs

# Multiple evaluators with conflict resolution
agent = DecisionAgent::Agent.new(
  evaluators: [rule_evaluator, ml_evaluator],
  scoring_strategy: DecisionAgent::Scoring::Consensus.new(minimum_agreement: 0.7),
  audit_adapter: DecisionAgent::Audit::LoggerAdapter.new
)

# Complex rules with nested conditions
rules = {
  version: "1.0",
  ruleset: "fraud_detection",
  rules: [{
    id: "suspicious_activity",
    if: {
      all: [
        { field: "amount", op: "gt", value: 10000 },
        { any: [
          { field: "user.country", op: "in", value: ["XX", "YY"] },
          { field: "velocity", op: "gt", value: 5 }
        ]}
      ]
    },
    then: { decision: "flag_for_review", weight: 0.95, reason: "Suspicious patterns detected" }
  }]
}

See examples/ for complete working examples.

DecisionAgent is designed to be thread-safe and FAST for use in multi-threaded environments:

• 10,000+ decisions/second throughput
• ~0.1ms average latency per decision
• Zero performance overhead from thread-safety
• Linear scalability with thread count

• Agent instances can be shared across threads safely
• Evaluators are immutable after initialization
• Decisions and Evaluations are deeply frozen
• File storage uses mutex-protected operations

# Safe: Reuse agent instance across threads
agent = DecisionAgent::Agent.new(evaluators: [evaluator])

Thread.new { agent.decide(context: { user_id: 1 }) }
Thread.new { agent.decide(context: { user_id: 2 }) }

# Safe: Share evaluators across agent instances
evaluator = DecisionAgent::Evaluators::JsonRuleEvaluator.new(rules_json: rules)
agent1 = DecisionAgent::Agent.new(evaluators: [evaluator])
agent2 = DecisionAgent::Agent.new(evaluators: [evaluator])

All data structures are deeply frozen to prevent mutation:

• Decision objects (decision, confidence, explanations, evaluations)
• Evaluation objects (decision, weight, reason, metadata)
• Context data
• Rule definitions in evaluators

This ensures safe concurrent access without race conditions.

Run the included benchmark to verify zero overhead:

ruby examples/thread_safe_performance.rb

See THREAD_SAFETY.md for detailed implementation guide and PERFORMANCE_AND_THREAD_SAFETY.md for detailed performance analysis.

✅ Perfect for:

• Regulated industries (healthcare, finance, legal)
• Complex business rule engines
• Audit trail requirements
• Explainable AI systems
• Multi-step decision workflows

❌ Not suitable for:

• Simple if/else logic (use plain Ruby)
• Pure AI/ML with no rules
• Single-step validations

Getting Started

• Installation
• Quick Start
• Examples

Core Features

• Versioning System - Version control for rules
• Web UI - Visual rule builder
• Web UI Setup - Setup guide

Performance & Thread-Safety

• Performance & Thread-Safety Summary - Benchmarks and production readiness
• Thread-Safety Implementation - Technical implementation guide

Reference

• API Contract - Full API reference
• Changelog - Version history

More Resources

• Wiki Home - Documentation index
• GitHub Issues - Report bugs or request features

1. Fork the repository
2. Create a feature branch
3. Add tests (maintain 90%+ coverage)
4. Submit a pull request

• Issues: GitHub Issues
• Documentation: Wiki
• Examples: examples/

MIT License - see LICENSE.txt

⭐ Star this repo if you find it useful!