Rust Rule Engine v0.13.4 🦀⚡

A high-performance rule engine for Rust with RETE-UL algorithm, CLIPS-inspired features, Plugin System, and GRL (Grule Rule Language) support. Designed for production use with good Drools compatibility.

🔗 GitHub | Documentation | Crates.io

✨ What's New in v0.13.4

⚡ Variable-to-Variable Comparison in RETE - Dynamic threshold comparisons!

🔄 Compare Variables - Direct comparison between fact fields (e.g., Facts.L1 > Facts.L1Min)
📊 Dynamic Thresholds - No hardcoded values, change thresholds on-the-fly
🎯 RETE-UL Support - Full integration with incremental engine
📝 GRL Syntax - Natural syntax: when (Facts.value > Facts.threshold)
⚡ Efficient Evaluation - Leverages RETE's pattern matching
🔧 Flexible Rules - Same rule adapts to different threshold configurations
✅ Production Ready - Battle-tested with complex eligibility rules

See Variable Comparison Demo → | Test Variable Comparison →

Previous Updates

v0.13.0 (Earlier)

⚡ Conflict Resolution Strategies - CLIPS/Drools-inspired rule ordering!

🎯 8 Strategies - Salience, LEX, MEA, Depth, Breadth, Simplicity, Complexity, Random
📊 Priority-Based - Control rule execution order with salience
🕐 Recency-Based - Most recent facts fire first (LEX)
🔍 Specificity - More specific rules fire first (Complexity, MEA)
⚙️ Performance - Simple rules before complex (Simplicity)
🔄 Dynamic Switching - Change strategies at runtime
✅ CLIPS Compatible - Industry-standard conflict resolution
📈 ~98% Drools Parity - Enhanced compatibility

See Conflict Resolution Demo → | CLIPS Features Guide →

Previous Updates

v0.12.0

🧪 Test CE (Conditional Element) - CLIPS-inspired arbitrary boolean expressions!

🔬 Test CE Syntax - Call arbitrary functions in rule conditions without operators
📝 GRL Support - Parse test(function(args)) directly from .grl files
🎯 Native Engine - Fully implemented with function registry
⚡ Truthy Evaluation - Automatic boolean conversion for all value types
🔗 Negation Support - Use !test() for negated conditions
🤝 Combined Conditions - Mix test() with regular conditions using AND/OR
📚 Multiple Arguments - Support functions with any number of arguments

See Test CE Demo →

v0.11.0

🎯 Deffacts System - Initial fact definitions (CLIPS feature)!

📦 Deffacts - Pre-defined fact sets for initial state
🔄 Reset Support - Restore original facts with reset_with_deffacts()
📋 Multiple Sets - Organize initial facts by category
✅ Template Integration - Type-safe initial facts
🏗️ Builder API - Fluent interface for defining deffacts

See Deffacts Demo →

v0.10.2

📧 Metadata Update - Corrected author email contact information

v0.10.1

🚀 RETE Performance Optimization + Comprehensive Benchmarks!

⚡ RETE Fixed - Eliminated infinite loop issue, now blazing fast
📊 Benchmarked - Comprehensive comparison: Traditional vs RETE
🔥 2-24x Faster - RETE shows 2x speedup at 10 rules, 24x at 50+ rules
✅ Production Ready - Max iterations guard, optimized agenda management
📈 Scalability Proven - ~5µs per rule, scales linearly

See Benchmark Results →

v0.10.0

🔧 Function Calls in WHEN - Call AI/custom functions directly in rule conditions
📋 Template System - Type-safe schema definitions for structured facts
🌍 Defglobal - Global variables with thread-safe access
📈 Drools Compatibility - ~97% Drools parity

See Release Notes → | CLIPS Features Guide →

🚀 Key Features

Native Engine

GRL Support - Full Grule-compatible syntax
Function Calls in WHEN - Call functions directly in conditions (NEW in v0.10.0)
Plugin System - 44+ actions, 33+ functions
Knowledge Base - Centralized rule management
Type Safety - Rust's compile-time guarantees
Production Ready - REST API, monitoring, health checks

RETE-UL Engine (Recommended for 50+ rules)

🚀 High Performance - Efficient RETE algorithm with incremental updates
🔥 RETE Algorithm - Advanced pattern matching with good Drools compatibility
🔄 Variable Comparison - Compare fact fields dynamically (L1 > L1Min) (v0.13.0)
📋 Template System - Type-safe structured facts (v0.10.0)
🌍 Defglobal - Global variables across firings (v0.10.0)
📦 Deffacts - Initial fact definitions (v0.11.0)
🧪 Test CE - Arbitrary boolean expressions in rules (v0.12.0)
⚡ Conflict Resolution - 8 CLIPS strategies (Salience, LEX, MEA, etc.) (v0.13.0)
🎯 Incremental Updates - Only re-evaluate affected rules
🧠 Working Memory - FactHandles with insert/update/retract
🔗 Variable Binding - Cross-pattern $var syntax
💾 Memoization - Efficient caching for repeated evaluations

Choose Your Engine:

< 10 rules → Native Engine (simpler API, plugin support)
10-50 rules → Either (RETE ~2x faster)
50+ rules → RETE-UL Engine (2-24x faster, highly recommended)
Both needs → Hybrid approach

📊 Performance at 50 rules: RETE shows good performance improvements over traditional engine!

📖 Engine Comparison Guide → | Quick Start Guide →

📦 Installation

[dependencies]
rust-rule-engine = "0.13.4"

Optional Features

# Enable streaming support
rust-rule-engine = { version = "0.13.4", features = ["streaming"] }

🎯 Quick Start

Option 1: Native Engine (Simple & Plugin-rich)

use rust_rule_engine::{RustRuleEngine, Facts, Value};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create engine with plugins
    let mut engine = RustRuleEngine::new();
    engine.load_default_plugins()?;

    // Load rules from GRL file
    engine.load_rules_from_file("rules/discount.grl")?;

    // Add facts
    let mut facts = Facts::new();
    facts.set("customer.tier", Value::String("gold".to_string()));
    facts.set("order.amount", Value::Float(1500.0));

    // Execute rules
    engine.execute(&mut facts)?;

    // Get result
    println!("Discount: {}", facts.get("order.discount"));

    Ok(())
}

GRL Rule Example (rules/discount.grl):

rule "GoldCustomerDiscount" salience 10 {
    when
        customer.tier == "gold" && order.amount > 1000
    then
        order.discount = order.amount * 0.15;
        Log("Applied 15% gold customer discount");
}

Option 2: RETE-UL Engine (High Performance)

use rust_rule_engine::rete::{
    IncrementalEngine, GrlReteLoader, TypedFacts, FactValue,
    TemplateBuilder, FieldType
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut engine = IncrementalEngine::new();

    // Optional: Define template for type safety
    let order_template = TemplateBuilder::new("Order")
        .required_string("order_id")
        .float_field("amount")
        .float_field("discount")
        .build();
    engine.templates_mut().register(order_template);

    // Load rules from GRL
    GrlReteLoader::load_from_file("rules/discount.grl", &mut engine)?;

    // Insert facts with validation
    let mut order = TypedFacts::new();
    order.set("order_id", FactValue::String("ORD-001".to_string()));
    order.set("amount", FactValue::Float(1500.0));

    let handle = engine.insert_with_template("Order", order)?;

    // Fire rules
    engine.reset();
    let fired = engine.fire_all();
    println!("Fired {} rules", fired.len());

    // Query results
    if let Some(order) = engine.working_memory().get(&handle) {
        println!("Discount: {:?}", order.data.get("discount"));
    }

    Ok(())
}

🔄 NEW: Variable-to-Variable Comparison (v0.13.0)

The RETE-UL engine now supports comparing variables directly with each other!

This powerful feature enables dynamic threshold comparisons without hardcoding values in rules, making your rule logic more flexible and reusable.

✨ Why Variable Comparison?

Traditional Approach (Hardcoded):

rule "CheckAge" {
    when customer.age > 18  // Hardcoded threshold
    then customer.eligible = true;
}

New Approach (Dynamic):

rule "CheckAge" {
    when customer.age > settings.minAge  // Dynamic threshold
    then customer.eligible = true;
}

📖 Real-World Example: Product Eligibility

Business Scenario: FamiCanxi product requires customers to meet dynamic thresholds for L1 and CM2 scores that can vary based on market conditions.

GRL Rule (famicanxi_rules.grl):

rule "FamiCanxi Product Eligibility Rule" salience 50 {
  when
    (Facts.L1 > Facts.L1Min) &&
    (Facts.CM2 > Facts.Cm2Min) &&
    (Facts.productCode == 1)
  then
    Facts.levelApprove = 1;
}

RETE-UL Implementation:

use rust_rule_engine::rete::{GrlReteLoader, IncrementalEngine, TypedFacts};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut engine = IncrementalEngine::new();

    // Load rule with variable comparisons
    GrlReteLoader::load_from_file("examples/famicanxi_rules.grl", &mut engine)?;

    // Insert facts with dynamic thresholds
    let mut facts = TypedFacts::new();
    facts.set("L1", 100i64);        // Customer score
    facts.set("L1Min", 50i64);      // Dynamic threshold (can change per request)
    facts.set("CM2", 80i64);        // Customer CM2 score
    facts.set("Cm2Min", 60i64);     // Dynamic threshold
    facts.set("productCode", 1i64);

    engine.insert("Facts".to_string(), facts);
    engine.reset();

    let fired = engine.fire_all();
    println!("Rules fired: {}", fired.len()); // Output: Rules fired: 1

    Ok(())
}

🎯 Key Benefits

Dynamic Business Rules - Change thresholds without modifying rule code
A/B Testing - Test different threshold configurations easily
Multi-Tenant Support - Different thresholds per customer/region
Configuration-Driven - Rules adapt to configuration changes
Reduced Code Duplication - One rule handles multiple scenarios

📊 Supported Comparisons

// Numeric comparisons
Facts.value > Facts.threshold
Facts.value >= Facts.minimum
Facts.value < Facts.maximum
Facts.value <= Facts.limit
Facts.value == Facts.target
Facts.value != Facts.excluded

// Mixed: variable with constant
Facts.value > Facts.threshold && Facts.status == "active"

// Multiple variable comparisons
(Facts.minValue < Facts.value) && (Facts.value < Facts.maxValue)

🧪 Test Examples

See complete working examples:

famicanxi_rete_test.rs - RETE-UL engine with variable comparison
famicanxi_grl_test.rs - Standard engine with GRL
test_variable_comparison.rs - Comprehensive test suite

🔧 Function Calls in WHEN Clause

v0.10.0 introduces the ability to call functions directly in rule conditions!

✨ Before (Rule Chaining)

rule "Step1: Call AI" {
    when Customer.needsCheck == true
    then set(Customer.sentiment, aiSentiment(Customer.feedback));
}

rule "Step2: Check Result" {
    when Customer.sentiment == "negative"
    then Alert("Negative feedback detected!");
}

✨ After (Direct Function Calls)

rule "Check Sentiment" {
    when aiSentiment(Customer.feedback) == "negative"
    then Alert("Negative feedback detected!");
}

📖 Use Cases

AI/ML Integration:

rule "Fraud Detection" {
    when aiFraud(Transaction.amount, Transaction.userId) == true
    then set(Transaction.status, "blocked");
}

Business Logic:

rule "Credit Check" {
    when creditScore(Customer.id) > 750
    then set(Customer.tier, "premium");
}

Data Validation:

rule "Email Validation" {
    when validateEmail(User.email) == false
    then set(User.error, "Invalid email format");
}

See ai_functions_in_when.rs for complete examples!

📚 Documentation

📖 Getting Started

Quick Start Guide - Choose and use your engine
Engine Comparison - Native vs RETE-UL decision guide
Examples - 30+ working examples

🔧 Core Features

Features Guide - All engine features explained
Plugin System - Built-in plugins & custom creation
Advanced Usage - Complex patterns & workflows
AI Integration - ML models & LLM integration

🚀 RETE-UL Engine

RETE Guide - Complete RETE-UL documentation
CLIPS Features - Template System & Defglobal
CLIPS Analysis - Feature comparison & roadmap

🌐 Distributed & Production

Streaming Engine - Real-time stream processing
Distributed Setup - Getting started with distributed mode
Distributed Architecture - Cluster setup & scaling
Distributed Features - Complete distributed guide
Performance Guide - Benchmarks & optimization

📋 Reference

API Reference - Complete API documentation
GRL Syntax - Rule language reference
Roadmap - Future plans & upcoming features
Release Notes - What's new in v0.10.0
Changelog - Complete changelog

🖥️ VS Code Extension

Install GRL Syntax Highlighting for .grl files:

Features:

Syntax highlighting for GRL
Snippets for rules, actions, functions
Auto-detection of .grl files

Install: Search grl-syntax-highlighting in VS Code Extensions

🎯 Use Cases

1. Business Rules Engine

// Pricing, discounts, loyalty programs
rule "VIPDiscount" {
    when customer.points > 1000
    then order.discount = 0.20;
}

2. Dynamic Eligibility & Thresholds (NEW!)

// Product eligibility with dynamic thresholds
rule "ProductEligibility" {
    when (customer.score > settings.minScore) &&
         (customer.income > settings.minIncome) &&
         (customer.age >= settings.minAge)
    then customer.eligible = true;
}

// Credit limit based on dynamic risk assessment
rule "CreditLimit" {
    when (customer.creditScore > risk.threshold) &&
         (customer.debtRatio < risk.maxDebtRatio)
    then customer.creditLimit = customer.income * risk.multiplier;
}

3. Fraud Detection

// Real-time fraud scoring
rule "HighRiskTransaction" {
    when transaction.amount > 10000 &&
         transaction.location != customer.usual_location
    then fraud.score = 0.85;
}

4. Workflow Automation

// Multi-step approval workflows
rule "ManagerApproval" agenda-group "approvals" {
    when request.amount > 5000
    then request.requires_manager = true;
}

5. Real-Time Systems

// IoT, monitoring, alerts
rule "TemperatureAlert" {
    when sensor.temp > 80
    then Alert.send("High temperature!");
}

More examples: examples/ directory

⚡ Performance

RETE-UL Engine Benchmarks

Pattern Matching: ~4µs per fact insertion (1000 facts)
Incremental Updates: 2x speedup (only affected rules)
Memoization: 99.99% cache hit rate
Template Validation: 1-2µs per fact
Global Variables: 120ns read, 180ns write

Native Engine Benchmarks

Rule Execution: ~10µs per rule (simple conditions)
Plugin Actions: ~2-5µs per action call
Facts Access: O(1) HashMap lookups

Comparison: Performance Guide

Automated GRL Test Harness

This repository includes a lightweight, data-driven test harness used to exercise the GRL examples in examples/rules and verify they still parse and run against the engine.

Purpose:

Provide end-to-end coverage for .grl example files without requiring full production action implementations.
Detect regressions in the parser, engine, and example rules.

Where to find it:

tests/grl_harness_data.rs — the primary data-driven harness. It reads tests/grl_cases.yml, constructs Facts, loads the .grl file(s), builds a KnowledgeBase, registers lightweight action handlers and functions, executes the engine, and performs simple assertions.
tests/grl_harness.rs — smaller smoke tests used by the harness and examples.
tests/grl_cases.yml — YAML-driven cases. Each case points at a .grl file and provides initial_facts and optional expect checks.

Why it uses minimal action handlers:

Many GRL samples call custom actions (e.g., apply_discount, sendAlert, setEcoMode, etc.). To exercise the rules end-to-end without requiring external systems, the harness registers small, no-op or fact-mutating action handlers. These handlers are only for testing and live in tests/grl_harness_data.rs.

How to run the harness (local development / CI):

# from repository root (zsh)
cargo test --tests -- --nocapture

What to look for:

The harness prints a per-case log (e.g., "=== Running case: fraud_detection ===") and a small set of logs generated by the registered handlers and functions.
Each case prints the number of rules fired. The harness currently performs lightweight assertions (e.g., rules fired, and simple fact field checks) — see tests/grl_harness_data.rs for details.

How to add or update cases:

Add a new case to tests/grl_cases.yml with fields: name, grl, initial_facts, and optional expect.
If the .grl uses custom actions not yet covered, either:
- Add a small test handler in tests/grl_harness_data.rs (follow the existing pattern), or
- Add sufficient initial_facts so rules can be exercised without that action being mandatory.
Run the harness and verify the new case behaves as expected.

Notes & next improvements:

The harness currently registers many minimal handlers to unblock rule execution; a future iteration should replace no-ops with tighter, case-specific assertions so the tests verify meaningful behavior instead of only successful execution.
There are some compiler warnings in the codebase (missing docs, unused-variable warnings). These do not block tests but can be cleaned up to keep CI logs tidy.

Questions or contributions: If you'd like, I can (a) strengthen per-case assertions, (b) consolidate test handlers into helpers, or (c) add a GitHub Actions workflow to run the harness in CI.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/KSD-CO/rust-rule-engine.git
cd rust-rule-engine

# Run tests
cargo test

# Run examples
cargo run --example rete_template_globals_demo

# Build documentation
cargo doc --open

📄 License

This project is licensed under the MIT License - see LICENSE file.

🙏 Acknowledgments

Inspired by:

Drools - JBoss Rule Engine
CLIPS - NASA C Language Integrated Production System
Grule - Go Rule Engine

Special Thanks:

Rust community for amazing tools and libraries
Contributors who helped improve the engine
Users providing valuable feedback

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: ttvuhm@gmail.com

📈 Stats

Crates.io downloads

Made with ❤️ by Ton That Vu

⭐ Star us on GitHub | 📦 Download from Crates.io

rust-rule-engine 0.13.4

Rust Rule Engine v0.13.4 🦀⚡

✨ What's New in v0.13.4

Previous Updates

v0.13.0 (Earlier)

Previous Updates

v0.12.0

v0.11.0

v0.10.2

v0.10.1

v0.10.0

🚀 Key Features

Native Engine

RETE-UL Engine (Recommended for 50+ rules)

📦 Installation

Optional Features

🎯 Quick Start

Option 1: Native Engine (Simple & Plugin-rich)

Option 2: RETE-UL Engine (High Performance)

🔄 NEW: Variable-to-Variable Comparison (v0.13.0)

✨ Why Variable Comparison?

📖 Real-World Example: Product Eligibility

🎯 Key Benefits

📊 Supported Comparisons

🧪 Test Examples

🔧 Function Calls in WHEN Clause

✨ Before (Rule Chaining)

✨ After (Direct Function Calls)

📖 Use Cases

📚 Documentation

📖 Getting Started

🔧 Core Features

🚀 RETE-UL Engine

🌐 Distributed & Production

📋 Reference

🖥️ VS Code Extension

🎯 Use Cases

1. Business Rules Engine

2. Dynamic Eligibility & Thresholds (NEW!)

3. Fraud Detection

4. Workflow Automation

5. Real-Time Systems

⚡ Performance

RETE-UL Engine Benchmarks

Native Engine Benchmarks

Automated GRL Test Harness

🤝 Contributing

Development Setup

📄 License

🙏 Acknowledgments

📞 Support

📈 Stats