decision_agent 0.2.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9fa9e4bed91c21f5402c19a902132014c30ab88b2acae6416d51831a544a0da
-  data.tar.gz: df95ffc19c834fc4a6c6bfe9fa72544d958e6715fef217e6ca680171c095caa8
+  metadata.gz: a016bb964d8daeb5676d84ba597f07af9e7b4816a8f075d3ca9feb6f1ddd2f44
+  data.tar.gz: ccc960d23a5c863b8e9be429b08188f32abe630d83e2008a3e70534401779d92
 SHA512:
-  metadata.gz: baf0c6e8b0a5895883cf6d3186f9f6576417a7bf943032aded6c5a989617a3dace19cb5f8d949d5488b10499d437f62519842ea22cc05751b9e5111ba3bc3860
-  data.tar.gz: 4196b121c6c061e0271278fba1f2861c830b6b358d09e0cf8cd29859aa05b7049b6eb3272f6ba961b9f9bc55a39786e1f1eb43f8728fb9039a82186da3ba9ae0
+  metadata.gz: 4f84301ecb298b3fdc3d39b2ca02e850345d2df13eb0c8834555f1b3f08241f243dee54fd044dfd0a37bd2fa32e690dca7583c69049af68d0e951572ca222ad0
+  data.tar.gz: a52598d8c6358ea03ed16a3fd23d68fbea1ef9619f1c4dec613359427a11e9290cd6f4b9f8816fb6673d436b59bdd23b986f816a23ecac185eae1e27b86e6dee

data/README.md

@@ -14,8 +14,8 @@ A production-grade, deterministic, explainable, and auditable decision engine fo
 DecisionAgent is designed for applications that require **deterministic, explainable, and auditable** decision-making:
 
 - ✅ **Deterministic** - Same input always produces same output
-- ✅ **Explainable** - Every decision includes human-readable reasoning
-- ✅ **Auditable** - Reproduce any historical decision exactly
+- ✅ **Explainable** - Every decision includes human-readable reasoning and machine-readable condition traces
+- ✅ **Auditable** - Reproduce any historical decision exactly with complete explainability
 - ✅ **Framework-agnostic** - Pure Ruby, works anywhere
 - ✅ **Production-ready** - Comprehensive testing ([Coverage Report](coverage.md)), error handling, and versioning
 
@@ -55,9 +55,12 @@ 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"]
+puts result.decision           # => "approve"
+puts result.confidence         # => 0.9
+puts result.explanations       # => ["High value transaction"]
+puts result.because            # => ["amount > 1000"]
+puts result.failed_conditions  # => []
+puts result.explainability     # => { decision: "approve", because: [...], failed_conditions: [] }
 ```
 
 See [Code Examples](docs/CODE_EXAMPLES.md) for more comprehensive examples.
@@ -69,25 +72,52 @@ See [Code Examples](docs/CODE_EXAMPLES.md) for more comprehensive examples.
 - **Conflict Resolution** - Weighted average, consensus, threshold, max weight
 - **Rich Context** - Nested data, dot notation, flexible operators
 - **Advanced Operators** - String, numeric, date/time, collection, and geospatial operators
+- **REST API Data Enrichment** - Fetch external data during decision-making with caching and circuit breaker
 
 ### Auditability & Compliance
 - **Complete Audit Trails** - Every decision fully logged
+- **Explainability Layer** - Machine-readable condition traces for every decision
+  - `result.because` - Conditions that led to the decision
+  - `result.failed_conditions` - Conditions that failed
+  - `result.explainability` - Complete machine-readable explainability data
 - **Deterministic Replay** - Reproduce historical decisions exactly
 - **RFC 8785 Canonical JSON** - Industry-standard deterministic hashing
 - **Compliance Ready** - HIPAA, SOX, regulatory compliance support
 
+### Testing & Simulation
+- **Simulation & What-If Analysis** - Test rule changes before deployment
+  - **Historical Replay / Backtesting** - Replay past decisions with new rules (CSV, JSON, database import)
+  - **What-If Analysis** - Simulate scenarios and sensitivity analysis with decision boundary visualization
+  - **Impact Analysis** - Quantify rule change effects (decision distribution, confidence shifts, performance impact)
+  - **Shadow Testing** - Compare new rules against production without affecting outcomes
+  - **Monte Carlo Simulation** - Model probabilistic inputs and understand decision outcome probabilities
+- **Batch Testing** - Test rules against large datasets with CSV/Excel import, coverage analysis, and resume capability
+- **A/B Testing** - Champion/Challenger testing with statistical significance analysis
+
+### Security & Access Control
+- **Role-Based Access Control (RBAC)** - Enterprise-grade authentication and authorization
+  - Built-in user/role system with bcrypt password hashing
+  - Configurable adapters for Devise, CanCanCan, Pundit, or custom auth systems
+  - 5 default roles (Admin, Editor, Viewer, Auditor, Approver) with 7 permissions
+  - Password reset functionality with secure token management
+  - Comprehensive access audit logging for compliance
+  - Web UI integration with login and user management pages
+
 ### Developer Experience
 - **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
+- **DMN 1.3 Support** - Industry-standard Decision Model and Notation with full FEEL expression language
+- **Visual Rule Builder** - Web UI for rule management and DMN modeler
+- **CLI Tools** - Command-line interface for DMN import/export and web server
 
 ### Production Features
 - **Real-time Monitoring** - Live dashboard with WebSocket updates
+- **Persistent Monitoring** - Database storage for long-term analytics (PostgreSQL, MySQL, SQLite)
 - **Prometheus Export** - Industry-standard metrics format
 - **Intelligent Alerting** - Anomaly detection with customizable rules
 - **Grafana Integration** - Pre-built dashboards and alert rules
-- **Version Control** - Full rule version control and rollback
+- **Version Control** - Full rule version control, rollback, and history ([Versioning Guide](docs/VERSIONING.md))
 - **Thread-Safe** - Safe for multi-threaded servers and background jobs
 - **High Performance** - 10,000+ decisions/second, ~0.1ms latency
 
@@ -121,6 +151,91 @@ end
 
 See [Web UI Integration Guide](docs/WEB_UI_RAILS_INTEGRATION.md) for detailed setup.
 
+## DMN (Decision Model and Notation) Support
+
+DecisionAgent includes full support for **DMN 1.3**, the industry standard for decision modeling:
+
+```ruby
+require 'decision_agent'
+require 'decision_agent/dmn/importer'
+require 'decision_agent/evaluators/dmn_evaluator'
+
+# Import DMN XML file
+importer = DecisionAgent::Dmn::Importer.new
+result = importer.import('path/to/model.dmn', created_by: 'user@example.com')
+
+# Create DMN evaluator
+evaluator = DecisionAgent::Evaluators::DmnEvaluator.new(
+  model: result[:model],
+  decision_id: 'loan_approval'
+)
+
+# Use with Agent
+agent = DecisionAgent::Agent.new(evaluators: [evaluator])
+result = agent.decide(context: { amount: 50000, credit_score: 750 })
+```
+
+**Features:**
+- **DMN 1.3 Standard** - Full OMG DMN 1.3 compliance
+- **FEEL Expressions** - Complete FEEL 1.3 language support (arithmetic, logical, functions)
+- **All Hit Policies** - UNIQUE, FIRST, PRIORITY, ANY, COLLECT
+- **Import/Export** - Round-trip conversion with other DMN tools (Camunda, Drools, IBM ODM)
+- **Visual Modeler** - Web-based DMN editor at `/dmn/editor`
+- **CLI Commands** - `decision_agent dmn import` and `decision_agent dmn export`
+
+See [DMN Guide](docs/DMN_GUIDE.md) for complete documentation and [DMN Examples](examples/dmn/README.md) for working examples.
+
+## REST API Data Enrichment
+
+DecisionAgent supports fetching external data during decision-making without manual context assembly:
+
+```ruby
+require 'decision_agent'
+
+# Configure data enrichment endpoints
+DecisionAgent.configure_data_enrichment do |config|
+  config.add_endpoint(:credit_bureau,
+    url: "https://api.creditbureau.com/v1/score",
+    method: :post,
+    auth: { type: :api_key, header: "X-API-Key" },
+    cache: { ttl: 3600, adapter: :memory }
+  )
+end
+
+# Use in rules with fetch_from_api operator
+rules = {
+  version: "1.0",
+  ruleset: "loan_approval",
+  rules: [{
+    id: "check_credit",
+    if: {
+      field: "credit_score",
+      op: "fetch_from_api",
+      value: {
+        endpoint: "credit_bureau",
+        params: { ssn: "{{customer.ssn}}" },
+        mapping: { score: "credit_score" }
+      }
+    },
+    then: { decision: "approve", weight: 0.8 }
+  }]
+}
+
+evaluator = DecisionAgent::Evaluators::JsonRuleEvaluator.new(rules_json: rules)
+agent = DecisionAgent::Agent.new(evaluators: [evaluator])
+result = agent.decide(context: { customer: { ssn: "123-45-6789" } })
+```
+
+**Features:**
+- **HTTP Client** - Support for GET, POST, PUT, DELETE methods
+- **Response Caching** - Configurable TTL per endpoint with memory adapter
+- **Circuit Breaker** - Fail-fast after N failures to prevent cascading failures
+- **Authentication** - API key, Basic Auth, and Bearer token support
+- **Template Parameters** - Use `{{path}}` syntax to reference context values
+- **Error Handling** - Graceful degradation with cached data fallback
+
+See [Data Enrichment Guide](docs/DATA_ENRICHMENT.md) for complete documentation and [Data Enrichment Example](examples/data_enrichment_example.rb) for working examples.
+
 ## Monitoring & Analytics
 
 Real-time monitoring, metrics, and alerting for production environments.
@@ -140,11 +255,155 @@ Open [http://localhost:4568](http://localhost:4568) for the monitoring dashboard
 
 **Features:**
 - Real-time dashboard with WebSocket updates
+- **Persistent Storage** - Database storage for long-term analytics (PostgreSQL, MySQL, SQLite)
 - Prometheus metrics export
 - Intelligent alerting with anomaly detection
 - Grafana integration with pre-built dashboards
 
-See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complete documentation.
+See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) and [Persistent Monitoring Guide](docs/PERSISTENT_MONITORING.md) for complete documentation.
+
+## Simulation & What-If Analysis
+
+DecisionAgent provides comprehensive simulation capabilities to test rule changes before deployment:
+
+```ruby
+require 'decision_agent/simulation/replay_engine'
+
+# Replay historical decisions with new rules
+replay_engine = DecisionAgent::Simulation::ReplayEngine.new(
+  agent: agent,
+  version_manager: version_manager
+)
+
+results = replay_engine.replay(historical_data: "decisions.csv")
+
+# What-if analysis
+whatif = DecisionAgent::Simulation::WhatIfAnalyzer.new(agent: agent)
+analysis = whatif.analyze(
+  base_context: { credit_score: 700, amount: 50000 },
+  scenarios: [
+    { credit_score: 750 },
+    { credit_score: 650 }
+  ]
+)
+
+# Impact analysis
+impact = DecisionAgent::Simulation::ImpactAnalyzer.new
+comparison = impact.compare(
+  baseline: baseline_evaluator,
+  proposed: proposed_evaluator,
+  contexts: test_contexts
+)
+```
+
+**Features:**
+- **Historical Replay** - Replay past decisions with CSV/JSON/database import
+- **What-If Analysis** - Scenario simulation with decision boundary visualization
+- **Impact Analysis** - Quantify rule change effects (decisions, confidence, performance)
+- **Shadow Testing** - Test new rules in production without affecting outcomes
+- **Monte Carlo Simulation** - Probabilistic decision modeling
+- **Web UI** - Complete simulation dashboard at `/simulation`
+
+See [Simulation Guide](docs/SIMULATION.md) for complete documentation and [Simulation Example](examples/simulation_example.rb) for working examples.
+
+## Role-Based Access Control (RBAC)
+
+Enterprise-grade authentication and authorization system:
+
+```ruby
+require 'decision_agent'
+
+# Configure RBAC (works with any auth system)
+DecisionAgent.configure_rbac(:devise_cancan, ability_class: Ability)
+
+# Or use built-in RBAC
+authenticator = DecisionAgent::Auth::Authenticator.new
+admin = authenticator.create_user(
+  email: "admin@example.com",
+  password: "secure_password",
+  roles: [:admin]
+)
+
+session = authenticator.login("admin@example.com", "secure_password")
+
+# Permission checks
+checker = DecisionAgent.permission_checker
+checker.can?(admin, :write)  # => true
+checker.can?(admin, :approve)  # => true
+```
+
+**Features:**
+- **Built-in User System** - User management with bcrypt password hashing
+- **5 Default Roles** - Admin, Editor, Viewer, Auditor, Approver
+- **Configurable Adapters** - Devise, CanCanCan, Pundit, or custom
+- **Password Reset** - Secure token-based password reset
+- **Access Audit Logging** - Comprehensive audit trail for compliance
+- **Web UI Integration** - Login page and user management interface
+
+See [RBAC Configuration Guide](docs/RBAC_CONFIGURATION.md) for complete documentation and [RBAC Examples](examples/rbac_configuration_examples.rb) for integration examples.
+
+## Batch Testing
+
+Test rules against large datasets with comprehensive analysis:
+
+```ruby
+require 'decision_agent/testing/batch_test_runner'
+
+runner = DecisionAgent::Testing::BatchTestRunner.new(agent: agent)
+
+# Import from CSV or Excel
+importer = DecisionAgent::Testing::BatchTestImporter.new
+scenarios = importer.import_csv("test_data.csv", {
+  context_fields: ["credit_score", "amount"],
+  expected_fields: ["expected_decision"]
+})
+
+# Run batch test
+results = runner.run(scenarios: scenarios)
+
+puts "Total: #{results[:total]}"
+puts "Passed: #{results[:passed]}"
+puts "Failed: #{results[:failed]}"
+puts "Coverage: #{results[:coverage]}"
+```
+
+**Features:**
+- **CSV/Excel Import** - Import test scenarios from files
+- **Database Import** - Load test data from databases
+- **Coverage Analysis** - Identify untested rule combinations
+- **Resume Capability** - Continue interrupted tests from checkpoint
+- **Progress Tracking** - Real-time progress updates for large imports
+- **Web UI** - Complete batch testing interface with file upload
+
+See [Batch Testing Guide](docs/BATCH_TESTING.md) for complete documentation.
+
+## A/B Testing
+
+Compare rule versions with statistical analysis:
+
+```ruby
+require 'decision_agent/testing/ab_test_manager'
+
+ab_manager = DecisionAgent::Testing::AbTestManager.new(version_manager: version_manager)
+
+test = ab_manager.create_test(
+  name: "loan_approval_v2",
+  champion_version: champion_version_id,
+  challenger_version: challenger_version_id,
+  traffic_split: 0.5
+)
+
+results = ab_manager.run_test(test_id: test.id, contexts: test_contexts)
+ab_manager.analyze_results(test_id: test.id)
+```
+
+**Features:**
+- **Champion/Challenger Testing** - Compare baseline vs proposed rules
+- **Statistical Significance** - P-value calculation and confidence intervals
+- **Traffic Splitting** - Configurable split ratios
+- **Decision Distribution Comparison** - Visualize differences in outcomes
+
+See [A/B Testing Guide](docs/AB_TESTING.md) for complete documentation.
 
 ## When to Use DecisionAgent
 
@@ -169,18 +428,31 @@ See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complet
 - [Examples Directory](examples/README.md) - Working examples with explanations
 
 ### Core Features
+- [Explainability Layer](docs/EXPLAINABILITY.md) - Machine-readable decision explanations with condition-level tracing
 - [Advanced Operators](docs/ADVANCED_OPERATORS.md) - String, numeric, date/time, collection, and geospatial operators
+- [Data Enrichment](docs/DATA_ENRICHMENT.md) - REST API data enrichment with caching and circuit breaker
+- [DMN Guide](docs/DMN_GUIDE.md) - Complete DMN 1.3 support guide
+- [DMN API Reference](docs/DMN_API.md) - DMN API documentation
+- [FEEL Reference](docs/FEEL_REFERENCE.md) - FEEL expression language reference
+- [DMN Migration Guide](docs/DMN_MIGRATION_GUIDE.md) - Migrating from JSON to DMN
+- [DMN Best Practices](docs/DMN_BEST_PRACTICES.md) - DMN modeling best practices
 - [Versioning System](docs/VERSIONING.md) - Version control for rules
+- [Simulation & What-If Analysis](docs/SIMULATION.md) - Historical replay, what-if analysis, impact analysis, and shadow testing
 - [A/B Testing](docs/AB_TESTING.md) - Compare rule versions with statistical analysis
+- [Batch Testing](docs/BATCH_TESTING.md) - Test rules against large datasets with CSV/Excel import
+- [RBAC Configuration](docs/RBAC_CONFIGURATION.md) - Role-based access control setup and integration
+- [RBAC Quick Reference](docs/RBAC_QUICK_REFERENCE.md) - Quick reference for RBAC configuration
 - [Web UI](docs/WEB_UI.md) - Visual rule builder
 - [Web UI Setup](docs/WEB_UI_SETUP.md) - Setup guide
 - [Web UI Rails Integration](docs/WEB_UI_RAILS_INTEGRATION.md) - Mount in Rails/Rack apps
 - [Monitoring & Analytics](docs/MONITORING_AND_ANALYTICS.md) - Real-time monitoring, metrics, and alerting
 - [Monitoring Architecture](docs/MONITORING_ARCHITECTURE.md) - System architecture and design
+- [Persistent Monitoring](docs/PERSISTENT_MONITORING.md) - Database storage for long-term analytics
 
 ### Performance & Thread-Safety
 - [Performance & Thread-Safety Summary](docs/PERFORMANCE_AND_THREAD_SAFETY.md) - Benchmarks and production readiness
 - [Thread-Safety Implementation](docs/THREAD_SAFETY.md) - Technical implementation guide
+- [Benchmarks](benchmarks/README.md) - Comprehensive benchmark suite and performance testing
 
 ### Reference
 - [API Contract](docs/API_CONTRACT.md) - Full API reference
@@ -204,6 +476,39 @@ All data structures are deeply frozen to prevent mutation, ensuring safe concurr
 
 See [Thread-Safety Guide](docs/THREAD_SAFETY.md) and [Performance Analysis](docs/PERFORMANCE_AND_THREAD_SAFETY.md) for details.
 
+**Run Benchmarks:**
+```bash
+# Run all benchmarks
+rake benchmark:all
+
+# Run specific benchmarks
+rake benchmark:basic      # Basic decision performance
+rake benchmark:threads    # Thread-safety and scalability
+rake benchmark:regression # Compare against baseline
+
+# See [Benchmarks Guide](benchmarks/README.md) for complete documentation
+```
+
+### Latest Benchmark Results
+
+**Last Updated:** 2026-01-06T04:03:29Z
+
+#### Performance Comparison
+
+| Metric | Latest (2026-01-06) | Previous (2026-01-06) | Change |
+|--------|--------------------------------------------------|------------------------------------------------------|--------|
+| Basic Throughput | 8966.04 decisions/sec | 9751.42 decisions/sec | ↓ 8.05% (degraded) |
+| Basic Latency | 0.1115 ms | 0.1025 ms | ↑ 8.78% (degraded) |
+| Multi-threaded (50 threads) Throughput | 8560.69 decisions/sec | 8849.86 decisions/sec | ↓ 3.27% (degraded) |
+| Multi-threaded (50 threads) Latency | 0.1168 ms | 0.113 ms | ↑ 3.36% (degraded) |
+
+**Environment:**
+- Ruby Version: 3.3.5
+- Hardware: x86_64
+- OS: Darwin
+- Git Commit: `aba46af5`
+
+> 💡 **Note:** Run `rake benchmark:regression` to generate new benchmark results. This section is automatically updated with the last 2 benchmark runs.
 ## Contributing
 
 1. Fork the repository

data/bin/decision_agent

@@ -3,6 +3,8 @@
 require "bundler/setup"
 require_relative "../lib/decision_agent"
 require_relative "../lib/decision_agent/web/server"
+require_relative "../lib/decision_agent/dmn/importer"
+require_relative "../lib/decision_agent/dmn/exporter"
 
 def print_help
   puts <<~HELP
@@ -14,6 +16,8 @@ def print_help
     Commands:
       web [PORT]         Start the web UI rule builder (default port: 4567)
       validate FILE      Validate a rules JSON file
+      dmn import FILE    Import a DMN XML file
+      dmn export RULESET OUTPUT  Export a ruleset to DMN XML
       version            Show version
       help               Show this help message
 
@@ -21,6 +25,8 @@ def print_help
       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 dmn import loan_decision.dmn
+      decision_agent dmn export loan_rules loan_export.dmn
       decision_agent version
 
     For more information, visit:
@@ -74,6 +80,75 @@ def validate_file(filepath)
   end
 end
 
+def dmn_import(filepath, ruleset_name: nil)
+  unless File.exist?(filepath)
+    puts "❌ Error: File not found: #{filepath}"
+    exit 1
+  end
+
+  begin
+    puts "📥 Importing DMN file: #{filepath}..."
+
+    importer = DecisionAgent::Dmn::Importer.new
+    result = importer.import(
+      filepath,
+      ruleset_name: ruleset_name,
+      created_by: ENV["USER"] || "cli_user"
+    )
+
+    puts "✅ Import successful!"
+    puts "   Model: #{result[:model].name}"
+    puts "   Decisions imported: #{result[:decisions_imported]}"
+    puts "   Namespace: #{result[:model].namespace}"
+
+    result[:model].decisions.each do |decision|
+      puts "   - Decision: #{decision.name} (#{decision.id})"
+      if decision.decision_table
+        puts "     Rules: #{decision.decision_table.rules.size}"
+        puts "     Hit Policy: #{decision.decision_table.hit_policy}"
+      end
+    end
+
+    if result[:versions].any?
+      puts ""
+      puts "   Versions created:"
+      result[:versions].each do |version|
+        puts "   - #{version[:rule_id]}: version #{version[:version]}"
+      end
+    end
+  rescue DecisionAgent::Dmn::InvalidDmnModelError, DecisionAgent::Dmn::DmnParseError => e
+    puts "❌ DMN Import Error:"
+    puts "   #{e.message}"
+    exit 1
+  rescue StandardError => e
+    puts "❌ Unexpected Error:"
+    puts "   #{e.message}"
+    puts "   #{e.backtrace.first}" if ENV["DEBUG"]
+    exit 1
+  end
+end
+
+def dmn_export(ruleset_id, output_path)
+  puts "📤 Exporting ruleset: #{ruleset_id}..."
+
+  exporter = DecisionAgent::Dmn::Exporter.new
+  dmn_xml = exporter.export(ruleset_id, output_path: output_path)
+
+  puts "✅ Export successful!"
+  puts "   Ruleset: #{ruleset_id}"
+  puts "   Output: #{output_path}"
+  puts "   Size: #{dmn_xml.bytesize} bytes"
+rescue DecisionAgent::Dmn::InvalidDmnModelError => e
+  puts "❌ Export Error:"
+  puts "   #{e.message}"
+  exit 1
+rescue StandardError => e
+  puts "❌ Unexpected Error:"
+  puts "   #{e.message}"
+  puts "   #{e.backtrace.first}" if ENV["DEBUG"]
+  exit 1
+end
+
 # Main CLI handler
 command = ARGV[0] || "help"
 
@@ -90,6 +165,35 @@ when "validate"
   end
   validate_file(ARGV[1])
 
+when "dmn"
+  subcommand = ARGV[1]
+  case subcommand
+  when "import"
+    if ARGV[2].nil?
+      puts "❌ Error: Please provide a DMN file path"
+      puts "Usage: decision_agent dmn import <file.xml>"
+      exit 1
+    end
+    ruleset_name = ARGV[3] # Optional ruleset name
+    dmn_import(ARGV[2], ruleset_name: ruleset_name)
+
+  when "export"
+    if ARGV[2].nil? || ARGV[3].nil?
+      puts "❌ Error: Please provide ruleset ID and output file path"
+      puts "Usage: decision_agent dmn export <ruleset> <output.xml>"
+      exit 1
+    end
+    dmn_export(ARGV[2], ARGV[3])
+
+  else
+    puts "❌ Unknown DMN subcommand: #{subcommand || '(none)'}"
+    puts ""
+    puts "DMN Commands:"
+    puts "  import FILE     Import a DMN XML file"
+    puts "  export RULESET OUTPUT  Export a ruleset to DMN XML"
+    exit 1
+  end
+
 when "version"
   puts "DecisionAgent version #{DecisionAgent::VERSION}"
 

data/lib/decision_agent/agent.rb

@@ -6,6 +6,17 @@ module DecisionAgent
   class Agent
     attr_reader :evaluators, :scoring_strategy, :audit_adapter
 
+    # Thread-safe cache for deterministic hash computation
+    # This significantly improves performance when the same context/evaluations
+    # are processed multiple times (common in benchmarks and high-throughput scenarios)
+    @hash_cache = {}
+    @hash_cache_mutex = Mutex.new
+    @hash_cache_max_size = 1000 # Limit cache size to prevent memory bloat
+
+    class << self
+      attr_reader :hash_cache, :hash_cache_mutex, :hash_cache_max_size
+    end
+
     def initialize(evaluators:, scoring_strategy: nil, audit_adapter: nil, validate_evaluations: nil)
       @evaluators = Array(evaluators)
       @scoring_strategy = scoring_strategy || Scoring::WeightedAverage.new
@@ -129,8 +140,68 @@ module DecisionAgent
 
     def compute_deterministic_hash(payload)
       hashable = payload.slice(:context, :evaluations, :decision, :confidence, :scoring_strategy)
+
+      # Use fast hash (MD5) as cache key to avoid expensive canonicalization on cache hits
+      # Optimized: Use direct JSON.to_json instead of recursive sorting for speed
+      # The cache key doesn't need perfect determinism, just good enough to catch duplicates
+      # This avoids the expensive sort_hash_keys recursion on every call
+      json_str = hashable.to_json
+      fast_key = Digest::MD5.hexdigest(json_str)
+
+      # Fast path: check cache without lock first (unsafe read, but acceptable for cache)
+      # This allows concurrent reads without mutex overhead
+      cache = self.class.hash_cache
+      cached_hash = cache[fast_key]
+      return cached_hash if cached_hash
+
+      # Cache miss - compute canonical JSON (required for deterministic hashing)
+      # This is expensive, but only happens on cache misses
       canonical = canonical_json(hashable)
-      Digest::SHA256.hexdigest(canonical)
+
+      # Compute SHA256 hash (also expensive, but only on cache misses)
+      computed_hash = Digest::SHA256.hexdigest(canonical)
+
+      # Store in cache (thread-safe, with size limit)
+      # Only lock when we need to write
+      self.class.hash_cache_mutex.synchronize do
+        # Double-check after acquiring lock (another thread may have added it)
+        return self.class.hash_cache[fast_key] if self.class.hash_cache[fast_key]
+
+        # Clear cache if it gets too large (simple FIFO eviction)
+        if self.class.hash_cache.size >= self.class.hash_cache_max_size
+          # Remove oldest 10% of entries (simple approximation)
+          keys_to_remove = self.class.hash_cache.keys.first(self.class.hash_cache_max_size / 10)
+          keys_to_remove.each { |key| self.class.hash_cache.delete(key) }
+        end
+        self.class.hash_cache[fast_key] = computed_hash
+      end
+
+      computed_hash
+    end
+
+    # Fast hash key generation using MD5 (much faster than canonical JSON + SHA256)
+    # Used as cache key to avoid expensive canonicalization on cache hits
+    # MD5 is sufficient for cache keys (collision resistance not critical, speed is)
+    def fast_hash_key(hashable)
+      # Create a deterministic string representation for hashing
+      # Use sorted JSON to ensure determinism (though not RFC 8785 canonical)
+      json_str = sort_hash_keys(hashable).to_json
+      Digest::MD5.hexdigest(json_str)
+    end
+
+    # Recursively sort hash keys for deterministic hashing
+    # This is faster than canonical JSON but still deterministic
+    # Note: This is still used by canonical_json indirectly, but fast_hash_key avoids it
+    def sort_hash_keys(obj)
+      case obj
+      when Hash
+        sorted = obj.sort.to_h
+        sorted.transform_values { |v| sort_hash_keys(v) }
+      when Array
+        obj.map { |v| sort_hash_keys(v) }
+      else
+        obj
+      end
     end
 
     # Uses RFC 8785 (JSON Canonicalization Scheme) for deterministic JSON serialization

data/lib/decision_agent/context.rb

@@ -4,6 +4,7 @@ module DecisionAgent
 
     def initialize(data)
       # Create a deep copy before freezing to avoid mutating the original
+      # This is necessary for thread-safety even if it adds some overhead
       data_hash = data.is_a?(Hash) ? data : {}
       @data = deep_freeze(deep_dup(data_hash))
     end