decision_agent 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5711ffe8ff5b3de7d808292d9cda3a0d8818ff77684b2da9a51a4794546a18b5
-  data.tar.gz: f0aba632f6da2eed6b0a07ca3c1ce73404652fbb4b57c8f812b4b9c679cbc1b4
+  metadata.gz: 6c8a831b21d5bb62dbb4948827cc0b4bc9bcf021b52f04a2d9141d1339287274
+  data.tar.gz: 97d80cab6513385dc9e9b4bddb7555da1e8629488ce358319aa0842e74cf41e1
 SHA512:
-  metadata.gz: 99b980e8fec99a261db15b0042891675903b83cf238f14604a7222c4efa30be3153c9ce5eda2857fcd1167cd30b4b1fd33090e4ff87d770959a5ba8b5fd7013b
-  data.tar.gz: be51208704d78c7b76b4dc956384d246e30d64ed8edcfe4d162e5ebd1221365a1e26057628634a56d62f0d04ac45c5482efb7556d614c6f28e6792c515276470
+  metadata.gz: dcfa8f3cc0a5931a1a163b97caf7586c17eddfee38850b52b832fa1a94d720342868c6823158597d0dafa14bf7df82b9d9b394fdffac3c74d06a556eca2b5c18
+  data.tar.gz: f183fc1b8c021e589571d0d9a97c3b2679fec3b529d2e73a76a4b7752a9792dcba77f4914de876c5448711416179dcbd0ba35b515fe1c4f2a74bcab27c1a873e

data/README.md

@@ -59,7 +59,11 @@ puts result.explanations  # => ["High value transaction"]
 
 ## Web UI - Visual Rule Builder
 
-Launch the visual rule builder for non-technical users:
+The DecisionAgent Web UI provides a visual interface for building and testing rules.
+
+### Standalone Usage
+
+Launch the visual rule builder:
 
 ```bash
 decision_agent web
@@ -67,45 +71,119 @@ decision_agent web
 
 Open [http://localhost:4567](http://localhost:4567) in your browser.
 
-<img width="1602" alt="DecisionAgent Web UI" src="https://github.com/user-attachments/assets/6ee6859c-f9f2-4f93-8bff-923986ccb1bc" />
+### Mount in Rails
 
-## Documentation
+Add to your `config/routes.rb`:
+
+```ruby
+require 'decision_agent/web/server'
+
+Rails.application.routes.draw do
+  # Mount DecisionAgent Web UI
+  mount DecisionAgent::Web::Server, at: '/decision_agent'
+end
+```
+
+Then visit `http://localhost:3000/decision_agent` in your browser.
+
+**With Authentication:**
+
+```ruby
+authenticate :user, ->(user) { user.admin? } do
+  mount DecisionAgent::Web::Server, at: '/decision_agent'
+end
+```
+
+### Mount in Rack/Sinatra Apps
+
+```ruby
+# config.ru
+require 'decision_agent/web/server'
+
+map '/decision_agent' do
+  run DecisionAgent::Web::Server
+end
+```
+
+<img width="1622" height="820" alt="Screenshot" src="https://github.com/user-attachments/assets/687e9ff6-669a-40f9-be27-085c614392d4" />
+
+See [Web UI Rails Integration Guide](wiki/WEB_UI_RAILS_INTEGRATION.md) for detailed setup instructions.
+
+## Monitoring & Analytics
+
+Real-time monitoring, metrics, and alerting for production environments.
+
+### Quick Start
+
+```ruby
+require 'decision_agent/monitoring/metrics_collector'
+require 'decision_agent/monitoring/dashboard_server'
+
+# Initialize metrics collection
+collector = DecisionAgent::Monitoring::MetricsCollector.new(window_size: 3600)
+
+# Start real-time dashboard
+DecisionAgent::Monitoring::DashboardServer.start!(
+  port: 4568,
+  metrics_collector: collector
+)
+
+# Record decisions
+agent = DecisionAgent::Agent.new(evaluators: [evaluator])
+result = agent.decide(context: { amount: 1500 })
+collector.record_decision(result, context, duration_ms: 25.5)
+```
+
+Open [http://localhost:4568](http://localhost:4568) for the monitoring dashboard.
+
+### Features
+
+- **Real-time Dashboard** - Live metrics with WebSocket updates
+- **Prometheus Export** - Industry-standard metrics format
+- **Intelligent Alerting** - Anomaly detection with customizable rules
+- **Grafana Integration** - Pre-built dashboards and alert rules
+- **Custom KPIs** - Track business-specific metrics
+- **Thread-Safe** - Production-ready performance
+
+### Prometheus & Grafana
 
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: 'decision_agent'
+    static_configs:
+      - targets: ['localhost:4568']
+    metrics_path: '/metrics'
 ```
-📚 DecisionAgent Documentation
-│
-├── 🚀 Getting Started
-│   ├── Installation (above)
-│   ├── Quick Start (above)
-│   └── Examples → examples/README.md
-│
-├── 📖 Core Documentation
-│   ├── Core Concepts → wiki/CORE_CONCEPTS.md
-│   ├── JSON Rule DSL → wiki/JSON_RULE_DSL.md
-│   ├── API Reference → wiki/API_CONTRACT.md
-│   └── Error Handling → wiki/ERROR_HANDLING.md
-│
-├── 🎯 Advanced Features
-│   ├── Versioning System → wiki/VERSIONING.md
-│   ├── Decision Replay → wiki/REPLAY.md
-│   ├── Advanced Usage → wiki/ADVANCED_USAGE.md
-│   └── Custom Components → wiki/ADVANCED_USAGE.md#custom-components
-│
-├── 🔌 Integration Guides
-│   ├── Rails Integration → wiki/INTEGRATION.md#rails
-│   ├── Redmine Plugin → wiki/INTEGRATION.md#redmine
-│   ├── Standalone Service → wiki/INTEGRATION.md#standalone
-│   └── Testing Guide → wiki/TESTING.md
-│
-├── 🎨 Web UI
-│   ├── User Guide → wiki/WEB_UI.md
-│   └── Setup Guide → wiki/WEB_UI_SETUP.md
-│
-└── 📝 Reference
-    ├── Changelog → wiki/CHANGELOG.md
-    └── Full Wiki Index → wiki/README.md
+
+Import the pre-built Grafana dashboard from [grafana/decision_agent_dashboard.json](grafana/decision_agent_dashboard.json).
+
+### Alert Management
+
+```ruby
+alert_manager = DecisionAgent::Monitoring::AlertManager.new(
+  metrics_collector: collector
+)
+
+# Add alert rules
+alert_manager.add_rule(
+  name: 'High Error Rate',
+  condition: AlertManager.high_error_rate(threshold: 0.1),
+  severity: :critical
+)
+
+# Register alert handlers
+alert_manager.add_handler do |alert|
+  SlackNotifier.notify("🚨 #{alert[:message]}")
+end
+
+# Start monitoring
+alert_manager.start_monitoring(interval: 60)
 ```
 
+See [Monitoring & Analytics Guide](wiki/MONITORING_AND_ANALYTICS.md) for complete documentation.
+
+
 ## Key Features
 
 ### Decision Making
@@ -124,11 +202,21 @@ Open [http://localhost:4567](http://localhost:4567) in your browser.
 - **JSON Rule DSL** - Non-technical users can write rules
 - **Visual Rule Builder** - Web UI for rule management
 
+### Monitoring & Observability
+- **Real-time Metrics** - Live dashboard with WebSocket updates (<1 second latency)
+- **Prometheus Export** - Industry-standard metrics format at `/metrics` endpoint
+- **Intelligent Alerting** - Anomaly detection with customizable rules and severity levels
+- **Grafana Integration** - Pre-built dashboards and alert configurations in `grafana/` directory
+- **Custom KPIs** - Track business-specific metrics with thread-safe operations
+- **MonitoredAgent** - Drop-in replacement that auto-records all metrics
+- **AlertManager** - Built-in anomaly detection (error rates, latency spikes, low confidence)
+
 ### Production Ready
 - **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
 
 ## Examples
 
@@ -162,6 +250,68 @@ rules = {
 
 See [examples/](examples/) for complete working examples.
 
+## Thread-Safety Guarantees
+
+DecisionAgent is designed to be **thread-safe and FAST** for use in multi-threaded environments:
+
+### Performance
+- **10,000+ decisions/second** throughput
+- **~0.1ms average latency** per decision
+- **Zero performance overhead** from thread-safety
+- **Linear scalability** with thread count
+
+### Safe Concurrent Usage
+- **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
+
+### Best Practices
+```ruby
+# 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])
+```
+
+### What's Frozen
+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.
+
+### RFC 8785 Canonical JSON
+DecisionAgent uses **RFC 8785 (JSON Canonicalization Scheme)** for deterministic audit hashing:
+
+- **Industry Standard** - Official IETF specification for canonical JSON
+- **Cryptographically Sound** - Ensures deterministic hashing of decision payloads
+- **Reproducible** - Same decision always produces same audit hash
+- **Interoperable** - Compatible with other systems using RFC 8785
+
+Every decision includes a deterministic SHA-256 hash in the audit payload, enabling:
+- Tamper detection in audit logs
+- Exact replay verification
+- Regulatory compliance documentation
+
+Learn more: [RFC 8785 Specification](https://datatracker.ietf.org/doc/html/rfc8785)
+
+### Performance Benchmark
+Run the included benchmark to verify zero overhead:
+```bash
+ruby examples/thread_safe_performance.rb
+```
+
+See [THREAD_SAFETY.md](wiki/THREAD_SAFETY.md) for detailed implementation guide and [PERFORMANCE_AND_THREAD_SAFETY.md](wiki/PERFORMANCE_AND_THREAD_SAFETY.md) for detailed performance analysis.
+
 ## When to Use DecisionAgent
 
 ✅ **Perfect for:**
@@ -176,6 +326,33 @@ See [examples/](examples/) for complete working examples.
 - Pure AI/ML with no rules
 - Single-step validations
 
+## Documentation
+
+**Getting Started**
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Examples](examples/README.md)
+
+**Core Features**
+- [Versioning System](wiki/VERSIONING.md) - Version control for rules
+- [Web UI](wiki/WEB_UI.md) - Visual rule builder
+- [Web UI Setup](wiki/WEB_UI_SETUP.md) - Setup guide
+- [Web UI Rails Integration](wiki/WEB_UI_RAILS_INTEGRATION.md) - Mount in Rails/Rack apps
+- [Monitoring & Analytics](wiki/MONITORING_AND_ANALYTICS.md) - Real-time monitoring, metrics, and alerting
+- [Monitoring Architecture](wiki/MONITORING_ARCHITECTURE.md) - System architecture and design
+
+**Performance & Thread-Safety**
+- [Performance & Thread-Safety Summary](wiki/PERFORMANCE_AND_THREAD_SAFETY.md) - Benchmarks and production readiness
+- [Thread-Safety Implementation](wiki/THREAD_SAFETY.md) - Technical implementation guide
+
+**Reference**
+- [API Contract](wiki/API_CONTRACT.md) - Full API reference
+- [Changelog](wiki/CHANGELOG.md) - Version history
+
+**More Resources**
+- [Wiki Home](wiki/README.md) - Documentation index
+- [GitHub Issues](https://github.com/samaswin87/decision_agent/issues) - Report bugs or request features
+
 ## Contributing
 
 1. Fork the repository

data/bin/decision_agent

@@ -24,15 +24,13 @@ 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
-  if defined?(Bundler) && !Bundler.const_defined?(:ORIGINAL_ENV)
-    Bundler.const_set(:ORIGINAL_ENV, ENV.to_h.dup)
-  end
+  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}"
@@ -60,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