decision_agent 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9fa9e4bed91c21f5402c19a902132014c30ab88b2acae6416d51831a544a0da
-  data.tar.gz: df95ffc19c834fc4a6c6bfe9fa72544d958e6715fef217e6ca680171c095caa8
+  metadata.gz: '095f5b6604126a4288548c648efbfb3f88cc94bf2a51ba84b21f422286c9c0f3'
+  data.tar.gz: 0f5475b14f32d3f7524ba63d21152bda4d088312dc1b154a6c15dd73f8e038e0
 SHA512:
-  metadata.gz: baf0c6e8b0a5895883cf6d3186f9f6576417a7bf943032aded6c5a989617a3dace19cb5f8d949d5488b10499d437f62519842ea22cc05751b9e5111ba3bc3860
-  data.tar.gz: 4196b121c6c061e0271278fba1f2861c830b6b358d09e0cf8cd29859aa05b7049b6eb3272f6ba961b9f9bc55a39786e1f1eb43f8728fb9039a82186da3ba9ae0
+  metadata.gz: 60f10c33779fac9cf26ed698a704b91e4ff65ca200d76870fa593a9074506b10a7791a471ab5cbb0fcdc9603145dc965131508619f0f1356f163cdaf069f49c9
+  data.tar.gz: d60e5eaf6d7350a55047594481c00360fa188e66db11e84cf863c7c734d1210c777e7fb358a689470d84256dd225b22376deb50648443dd0257a5041816086c1

data/README.md

@@ -80,7 +80,8 @@ See [Code Examples](docs/CODE_EXAMPLES.md) for more comprehensive examples.
 - **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
 
 ### Production Features
 - **Real-time Monitoring** - Live dashboard with WebSocket updates
@@ -121,6 +122,40 @@ 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.
+
 ## Monitoring & Analytics
 
 Real-time monitoring, metrics, and alerting for production environments.
@@ -170,6 +205,11 @@ See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complet
 
 ### Core Features
 - [Advanced Operators](docs/ADVANCED_OPERATORS.md) - String, numeric, date/time, collection, and geospatial operators
+- [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
 - [A/B Testing](docs/AB_TESTING.md) - Compare rule versions with statistical analysis
 - [Web UI](docs/WEB_UI.md) - Visual rule builder

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/dmn/adapter.rb

@@ -0,0 +1,135 @@
+require_relative "feel/evaluator"
+
+module DecisionAgent
+  module Dmn
+    # Converts DMN decision tables to DecisionAgent JSON rule format
+    class Adapter
+      def initialize(decision_table)
+        @table = decision_table
+        @feel = Feel::Evaluator.new
+      end
+
+      # Convert DMN decision table to JSON rules
+      def to_json_rules
+        {
+          "version" => "1.0",
+          "ruleset" => @table.id,
+          "description" => "Converted from DMN decision table",
+          "rules" => convert_rules
+        }
+      end
+
+      private
+
+      def convert_rules
+        @table.rules.map.with_index do |rule, idx|
+          convert_rule(rule, idx)
+        end
+      end
+
+      def convert_rule(rule, idx)
+        {
+          "id" => rule.id || "rule_#{idx + 1}",
+          "if" => build_condition(rule),
+          "then" => build_output(rule),
+          "description" => rule.description
+        }.compact
+      end
+
+      def build_condition(rule)
+        # Build 'all' condition combining all input entries
+        conditions = []
+
+        rule.input_entries.each_with_index do |entry, idx|
+          next if entry == "-" # Skip "don't care" entries
+
+          input = @table.inputs[idx]
+          condition = convert_feel_to_condition(entry, input.expression || input.label)
+          conditions << condition if condition
+        end
+
+        # If no conditions, return a condition that always matches
+        # Use a simple true condition instead of empty "all" array
+        return { "field" => "__always_match__", "op" => "eq", "value" => true } if conditions.empty?
+
+        # If only one condition, return it directly
+        return conditions.first if conditions.size == 1
+
+        # Otherwise, wrap in 'all'
+        { "all" => conditions }
+      end
+
+      def convert_feel_to_condition(feel_expression, field_name)
+        parsed = @feel.parse_expression(feel_expression)
+
+        # Ensure we have valid operator and value
+        operator = parsed[:operator] || "eq"
+        value = parsed[:value]
+
+        # If value is nil, we can't create a valid condition
+        if value.nil?
+          warn "Warning: FEEL expression '#{feel_expression}' parsed to nil value, skipping"
+          return nil
+        end
+
+        {
+          "field" => field_name,
+          "op" => operator,
+          "value" => value
+        }
+      rescue StandardError => e
+        # Log warning and skip invalid expressions
+        warn "Warning: Could not parse FEEL expression '#{feel_expression}': #{e.message}"
+        nil
+      end
+
+      def build_output(rule)
+        # For Phase 2A, we take the first output as the decision
+        # Multi-output support in Phase 2B
+        output_value = rule.output_entries.first
+
+        # Parse FEEL expression in output value (remove quotes from string literals)
+        parsed_value = parse_output_value(output_value)
+
+        # Ensure we always have a valid decision value (not nil or empty string)
+        parsed_value = "no_decision" if parsed_value.nil? || (parsed_value.is_a?(String) && parsed_value.empty?)
+
+        {
+          "decision" => parsed_value,
+          "weight" => 1.0,
+          "reason" => rule.description || "DMN rule #{rule.id} matched"
+        }
+      end
+
+      def parse_output_value(value)
+        # Handle nil values
+        return nil if value.nil?
+
+        # If already not a string, return as-is (number, boolean, etc.)
+        return value unless value.is_a?(String)
+
+        value_str = value.to_s.strip
+
+        # Return nil for empty strings
+        return nil if value_str.empty?
+
+        # Remove quotes from string literals
+        return value_str[1..-2] if value_str.start_with?('"') && value_str.end_with?('"')
+
+        # Try to parse as number
+        if value_str.match?(/^-?\d+\.\d+$/)
+          return value_str.to_f
+        elsif value_str.match?(/^-?\d+$/)
+          return value_str.to_i
+        end
+
+        # Boolean
+        return true if value_str.downcase == "true"
+        return false if value_str.downcase == "false"
+
+        # Return as-is (unquoted string)
+        value_str
+      end
+    end
+  end
+end

data/lib/decision_agent/dmn/cache.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "digest"
+require "zlib"
+
+module DecisionAgent
+  module Dmn
+    # DMN Evaluation Cache
+    # Provides caching for DMN model parsing and evaluation results
+    class EvaluationCache
+      attr_reader :model_cache, :result_cache, :stats
+
+      def initialize(max_model_cache_size: 100, max_result_cache_size: 1000, ttl: 3600)
+        @model_cache = {}
+        @result_cache = {}
+        @max_model_cache_size = max_model_cache_size
+        @max_result_cache_size = max_result_cache_size
+        @ttl = ttl # Time to live in seconds
+        @mutex = Mutex.new
+        @stats = {
+          model_cache_hits: 0,
+          model_cache_misses: 0,
+          result_cache_hits: 0,
+          result_cache_misses: 0
+        }
+      end
+
+      # Cache a parsed DMN model
+      def cache_model(model_id, model)
+        @mutex.synchronize do
+          # Evict oldest if cache is full
+          evict_oldest_model if @model_cache.size >= @max_model_cache_size
+
+          @model_cache[model_id] = {
+            model: model,
+            cached_at: Time.now.to_i
+          }
+        end
+      end
+
+      # Get a cached model
+      def get_model(model_id)
+        @mutex.synchronize do
+          entry = @model_cache[model_id]
+
+          if entry && !expired?(entry[:cached_at])
+            @stats[:model_cache_hits] += 1
+            entry[:model]
+          else
+            @stats[:model_cache_misses] += 1
+            @model_cache.delete(model_id) if entry
+            nil
+          end
+        end
+      end
+
+      # Cache an evaluation result
+      def cache_result(decision_id, context_hash, result)
+        @mutex.synchronize do
+          # Evict oldest if cache is full
+          evict_oldest_result if @result_cache.size >= @max_result_cache_size
+
+          cache_key = generate_result_key(decision_id, context_hash)
+          @result_cache[cache_key] = {
+            result: result,
+            cached_at: Time.now.to_i
+          }
+        end
+      end
+
+      # Get a cached evaluation result
+      def get_result(decision_id, context_hash)
+        @mutex.synchronize do
+          cache_key = generate_result_key(decision_id, context_hash)
+          entry = @result_cache[cache_key]
+
+          if entry && !expired?(entry[:cached_at])
+            @stats[:result_cache_hits] += 1
+            entry[:result]
+          else
+            @stats[:result_cache_misses] += 1
+            @result_cache.delete(cache_key) if entry
+            nil
+          end
+        end
+      end
+
+      # Clear all caches
+      def clear
+        @mutex.synchronize do
+          @model_cache.clear
+          @result_cache.clear
+          @stats.each_key { |k| @stats[k] = 0 }
+        end
+      end
+
+      # Clear model cache
+      def clear_models
+        @mutex.synchronize do
+          @model_cache.clear
+        end
+      end
+
+      # Clear result cache
+      def clear_results
+        @mutex.synchronize do
+          @result_cache.clear
+        end
+      end
+
+      # Get cache statistics
+      def statistics
+        @mutex.synchronize do
+          model_hit_rate = calculate_hit_rate(@stats[:model_cache_hits], @stats[:model_cache_misses])
+          result_hit_rate = calculate_hit_rate(@stats[:result_cache_hits], @stats[:result_cache_misses])
+
+          @stats.merge(
+            model_cache_size: @model_cache.size,
+            result_cache_size: @result_cache.size,
+            model_hit_rate: model_hit_rate,
+            result_hit_rate: result_hit_rate
+          )
+        end
+      end
+
+      private
+
+      def expired?(cached_at)
+        (Time.now.to_i - cached_at) > @ttl
+      end
+
+      def evict_oldest_model
+        return if @model_cache.empty?
+
+        oldest_key = @model_cache.min_by { |_k, v| v[:cached_at] }[0]
+        @model_cache.delete(oldest_key)
+      end
+
+      def evict_oldest_result
+        return if @result_cache.empty?
+
+        oldest_key = @result_cache.min_by { |_k, v| v[:cached_at] }[0]
+        @result_cache.delete(oldest_key)
+      end
+
+      def generate_result_key(decision_id, context_hash)
+        Digest::SHA256.hexdigest("#{decision_id}:#{context_hash}")
+      end
+
+      def calculate_hit_rate(hits, misses)
+        total = hits + misses
+        total.positive? ? (hits.to_f / total * 100).round(2) : 0
+      end
+    end
+
+    # Enhanced DMN Evaluator with Caching
+    class CachedDmnEvaluator
+      attr_reader :cache, :evaluator
+
+      def initialize(dmn_model:, decision_id:, cache: nil, enable_caching: true)
+        @dmn_model = dmn_model
+        @decision_id = decision_id
+        @cache = cache || EvaluationCache.new
+        @enable_caching = enable_caching
+
+        # Create the underlying evaluator
+        @evaluator = Evaluators::DmnEvaluator.new(
+          dmn_model: dmn_model,
+          decision_id: decision_id
+        )
+      end
+
+      # Evaluate with caching
+      def evaluate(context:)
+        return @evaluator.evaluate(context: context) unless @enable_caching
+
+        # Generate context hash for cache key
+        context_hash = generate_context_hash(context)
+
+        # Try to get cached result
+        cached_result = @cache.get_result(@decision_id, context_hash)
+        return cached_result if cached_result
+
+        # Evaluate and cache result
+        result = @evaluator.evaluate(context: context)
+        @cache.cache_result(@decision_id, context_hash, result)
+
+        result
+      end
+
+      # Warm up cache with common inputs
+      def warm_cache(input_samples)
+        input_samples.each do |inputs|
+          context = Context.new(inputs)
+          evaluate(context: context)
+        end
+      end
+
+      # Get cache statistics
+      def cache_stats
+        @cache.statistics
+      end
+
+      # Clear cache
+      def clear_cache
+        @cache.clear_results
+      end
+
+      private
+
+      def generate_context_hash(context)
+        # Create a deterministic hash of the context
+        # Use CRC32 for better performance (much faster than SHA256, still deterministic)
+        data = context.is_a?(Context) ? context.to_h : context
+
+        # For deterministic hashing, sort keys and create a stable representation
+        # Use CRC32 which is faster than SHA256 while still being deterministic
+        sorted_data = data.sort.to_h
+        json_str = sorted_data.to_json
+        Zlib.crc32(json_str)
+      end
+    end
+
+    # FEEL Expression Cache
+    # Caches compiled/parsed FEEL expressions for reuse
+    class FeelExpressionCache
+      def initialize(max_size: 500)
+        @cache = {}
+        @max_size = max_size
+        @mutex = Mutex.new
+        @stats = { hits: 0, misses: 0 }
+      end
+
+      # Cache a parsed FEEL expression
+      def cache_expression(expression_string, parsed_expression)
+        @mutex.synchronize do
+          evict_oldest if @cache.size >= @max_size
+
+          @cache[expression_string] = {
+            expression: parsed_expression,
+            accessed_at: Time.now.to_i,
+            access_count: 0
+          }
+        end
+      end
+
+      # Get a cached expression
+      def get_expression(expression_string)
+        @mutex.synchronize do
+          entry = @cache[expression_string]
+
+          if entry
+            @stats[:hits] += 1
+            entry[:accessed_at] = Time.now.to_i
+            entry[:access_count] += 1
+            entry[:expression]
+          else
+            @stats[:misses] += 1
+            nil
+          end
+        end
+      end
+
+      # Clear cache
+      def clear
+        @mutex.synchronize do
+          @cache.clear
+          @stats[:hits] = 0
+          @stats[:misses] = 0
+        end
+      end
+
+      # Get statistics
+      def statistics
+        @mutex.synchronize do
+          hit_rate = @stats[:hits] + @stats[:misses]
+          hit_rate = hit_rate.positive? ? (@stats[:hits].to_f / hit_rate * 100).round(2) : 0
+
+          {
+            size: @cache.size,
+            hits: @stats[:hits],
+            misses: @stats[:misses],
+            hit_rate: hit_rate,
+            most_accessed: most_accessed_expressions
+          }
+        end
+      end
+
+      private
+
+      def evict_oldest
+        return if @cache.empty?
+
+        # Evict least recently accessed
+        oldest_key = @cache.min_by { |_k, v| v[:accessed_at] }[0]
+        @cache.delete(oldest_key)
+      end
+
+      def most_accessed_expressions
+        @cache.sort_by { |_k, v| -v[:access_count] }.first(5).map do |expr, data|
+          { expression: expr, count: data[:access_count] }
+        end
+      end
+    end
+  end
+end