Rust Rule Engine v0.9.0 🦀⚡

A high-performance rule engine for Rust with Plugin System, Built-in Utilities, GRL (Grule Rule Language) support, and advanced pattern matching capabilities. Designed for production use with comprehensive error handling, type safety, and extensibility.

🔗 GitHub Repository | Documentation | Crates.io

� Table of Contents

• 🚀 Key Features
• 📦 Installation
• 🎯 Quick Start
  • Basic Rule Engine with Built-in Plugins
  • Simple Rule without Plugins
• 🔌 Plugin System
  • Built-in Plugins Overview
  • Creating Custom Plugins
• 🎯 Advanced Features
  • Knowledge Base Management
  • Complex Data Objects
  • Method Calls and Functions
  • Error Handling and Debugging
• 📚 Examples
• 🔧 Configuration
  • Engine Configuration
  • Plugin Configuration
• 🚀 Performance
• 🗺 Roadmap
• 🧩 Advanced Pattern Matching
• 🎯 Rule Attributes
• 🚨 Advanced Action Handlers
• 🌊 Advanced Workflow Engine
• 🤖 AI Integration
• 🎨 Visual Rule Builder
• 🌐 REST API with Monitoring
• ⚡ Performance & Architecture
• 📋 Changelog
• 🎯 GRL Rule Language Features
• 🌐 Distributed & Cloud Features
• 📋 API Reference
• 🤝 Contributing
• 📄 License
• 🙏 Acknowledgments
• 📞 Support

�🚀 Key Features

🔥 NEW in v0.9.0: Plugin System

• Modular Plugin Architecture: Extensible plugin system with lifecycle management
• Built-in Plugin Suite: 44+ actions & 33+ functions for common operations
• Plugin Health Monitoring: Real-time health checks and status tracking
• Hot-reload Support: Dynamic plugin loading and unloading
• Custom Plugin Creation: Easy-to-use RulePlugin trait for custom extensions

🎯 Core Engine Features

• GRL Support: Full Grule-compatible syntax with method calls and object interactions
• Knowledge Base: Centralized rule management with salience and priority control
• Working Memory: Advanced facts system for complex data relationships
• Type Safety: Rust's type system ensures runtime safety and performance
• High Performance: Optimized execution with cycle detection and parallel processing
• Flexible Facts API: Support for nested objects, arrays, and complex data structures

🧩 Advanced Pattern Matching

• EXISTS Pattern: Check if at least one fact matches condition (exists(...))
• NOT Pattern: Check if no facts match condition (!exists(...))
• FORALL Pattern: Check if all facts of a type match condition (forall(...))
• Complex Patterns: Combine patterns with logical operators (AND, OR, NOT)
• Drools Compatibility: ~85% compatible with Drools pattern matching

🎯 Rule Attributes & Workflow

• Agenda Groups: Organize rules into execution phases for workflow control
• Activation Groups: Mutually exclusive rule execution with salience priority
• Lock-on-Active: Prevent rules from firing multiple times per agenda activation
• Date Effective/Expires: Time-based rule activation with DateTime support
• No-Loop Protection: Prevent infinite rule self-activation
• Salience Control: Priority-based rule execution ordering

🚨 Action Handler System

• Custom Action Execution: Register handlers for real business logic
• Parameter Resolution: Automatic fact value substitution in parameters
• External System Integration: Connect to emails, databases, APIs, services
• Error Handling: Graceful failure handling with meaningful messages
• Facts Integration: Full access to rule engine fact data within handlers

🌊 Workflow Engine Features

• Scheduled Task System: Time-based task execution with flexible scheduling
• Workflow State Tracking: Real-time workflow monitoring and progress tracking
• Dynamic Rule Activation: Context-aware rule execution based on workflow state
• Comprehensive Analytics: Detailed workflow performance metrics and insights

🛠 Built-in Plugin Suite

• String Utilities: 13 actions, 7 functions for text manipulation
• Math Operations: 12 actions, 8 functions for calculations
• Date/Time: 8 actions, 6 functions for temporal operations
• Data Validation: 6 actions, 6 functions for input validation
• Collections: 7 actions, 6 functions for array/object manipulation

🤖 AI Integration

• Sentiment Analysis: Real-time text sentiment evaluation
• Fraud Detection: ML-powered fraud scoring and detection
• Predictive Analytics: Customer tier prediction and scoring
• LLM Reasoning: Large Language Model decision support
• Real-time ML Scoring: Dynamic model inference in rules

🌐 Production Features

• REST API: Complete web API with analytics monitoring
• Real-time Analytics: Live performance monitoring and insights
• Health Checks: Comprehensive system health monitoring
• CORS Support: Cross-origin resource sharing
• Memory Management: Automatic cleanup and retention policies
• Error Handling: Proper HTTP status codes and error messages

⚡ Performance & Architecture

• Ultra-fast Execution: Rules execute in microseconds (2-5µs)
• Efficient Parsing: GRL rules parse in under 2µs
• Low Memory Footprint: Minimal overhead per rule (~1-2KB)
• Zero GC Pauses: No garbage collection overhead
• Parallel Processing: Multi-threaded rule execution when safe
• Dependency Analysis: AST-based conflict detection and optimization

📦 Installation

Add this to your Cargo.toml:

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

🎯 Quick Start

Basic Rule Engine with Built-in Plugins

use rust_rule_engine::*;
use rust_rule_engine::engine::plugin::RulePlugin;
use rust_rule_engine::plugins::*;

fn main() -> Result<()> {
    // Create engine with knowledge base
    let kb = KnowledgeBase::new("Demo");
    let mut engine = RustRuleEngine::new(kb);
    let mut facts = Facts::new();

    // Load built-in plugins
    let string_plugin = StringUtilsPlugin::new();
    let math_plugin = MathUtilsPlugin::new();
    let validation_plugin = ValidationPlugin::new();

    // Register plugins
    string_plugin.register_actions(&mut engine)?;
    string_plugin.register_functions(&mut engine)?;
    math_plugin.register_actions(&mut engine)?;
    math_plugin.register_functions(&mut engine)?;
    validation_plugin.register_actions(&mut engine)?;
    validation_plugin.register_functions(&mut engine)?;

    // Set up data
    facts.set("user.email".to_string(), Value::String("user@example.com".to_string()));
    facts.set("user.age".to_string(), Value::Number(25.0));
    facts.set("order.amount".to_string(), Value::Number(150.0));

    // Define GRL rule with plugin actions
    let rule_content = r#"
    rule "UserValidationAndDiscount" salience 10 {
        when
            isEmail(user.email) == true &&
            inRange(user.age, 18, 65) == true &&
            user.order.amount > 100
        then
            ValidateEmail("user.email", "email_valid");
            ValidateRange("user.age", 18, 65, "age_valid");
            Multiply("order.amount", 0.9, "discounted_amount");
            ToUpperCase("user.status", "display_status");
    }
    "#;

    // Parse and add rule to knowledge base
    let rules = GRLParser::parse_rules(rule_content)?;
    for rule in rules {
        engine.add_rule_to_kb(rule)?;
    }

    // Execute rules
    let result = engine.execute(&facts)?;
    println!("Rules executed: {}", result.rules_executed);
    println!("Email valid: {:?}", facts.get("email_valid"));
    println!("Age valid: {:?}", facts.get("age_valid"));
    println!("Discounted amount: {:?}", facts.get("discounted_amount"));

    Ok(())
}

Simple Rule without Plugins

use rust_rule_engine::*;

fn main() -> Result<()> {
    let kb = KnowledgeBase::new("SimpleDemo");
    let mut engine = RustRuleEngine::new(kb);
    let mut facts = Facts::new();

    // Set up facts
    facts.set("Customer.Age".to_string(), Value::Integer(25));
    facts.set("Customer.Country".to_string(), Value::String("US".to_string()));
    facts.set("Order.Total".to_string(), Value::Number(150.0));

    // Define GRL rule
    let rule = r#"
    rule "DiscountRule" salience 20 {
        when
            Customer.Age >= 18 && 
            Customer.Country == "US" && 
            Order.Total > 100
        then
            Order.DiscountRate = 0.15;
            Order.FreeShipping = true;
    }
    "#;

    // Parse and execute
    let rules = GRLParser::parse_rules(rule)?;
    for r in rules {
        engine.add_rule_to_kb(r)?;
    }

    let result = engine.execute(&facts)?;
    println!("Discount applied: {:?}", facts.get("Order.DiscountRate"));
    println!("Free shipping: {:?}", facts.get("Order.FreeShipping"));

    Ok(())
}

🔌 Plugin System

Built-in Plugins Overview

The v0.9.0 release includes a comprehensive plugin suite:

📝 String Utilities Plugin

// Actions: ToUpperCase, ToLowerCase, StringTrim, StringLength, 
//          StringContains, StringReplace, StringSplit, StringJoin
// Functions: concat, repeat, substring, padLeft, padRight

ToUpperCase("input_text", "output_text");
let result = concat("Hello", " World"); // "Hello World"

🔢 Math Operations Plugin

// Actions: Add, Subtract, Multiply, Divide, Modulo, Power, Abs, Round, Ceil, Floor
// Functions: max, min, sqrt, sum, avg, random

Add("num1", "num2", "result");
let maximum = max(10.5, 8.2); // 10.5

📅 Date/Time Plugin

// Actions: CurrentDate, CurrentTime, FormatDate, ParseDate, AddDays, AddHours, DateDiff, IsWeekend
// Functions: now, today, dayOfWeek, dayOfYear, year, month, day

CurrentDate("current_date");
let day = dayOfWeek("2023-10-15"); // Returns day number

✅ Validation Plugin

// Actions: ValidateEmail, ValidatePhone, ValidateUrl, ValidateRegex, ValidateRange, ValidateLength, ValidateNotEmpty, ValidateNumeric
// Functions: isEmail, isPhone, isUrl, isNumeric, isEmpty, inRange

ValidateEmail("user.email", "email_valid");
let valid = isEmail("test@example.com"); // true

📋 Collection Operations Plugin

// Actions: ArrayLength, ArrayPush, ArrayPop, ArraySort, ArrayFilter, ArrayMap, ArrayFind, ObjectKeys, ObjectValues, ObjectMerge
// Functions: length, contains, first, last, reverse, join, slice, keys, values

ArrayLength("my_array", "array_length");
let size = length([1, 2, 3, 4]); // 4

Creating Custom Plugins

use rust_rule_engine::engine::plugin::{RulePlugin, PluginMetadata, PluginState, PluginHealth};

pub struct MyCustomPlugin {
    metadata: PluginMetadata,
}

impl MyCustomPlugin {
    pub fn new() -> Self {
        Self {
            metadata: PluginMetadata {
                name: "my_custom_plugin".to_string(),
                version: "1.0.0".to_string(),
                description: "My custom plugin".to_string(),
                author: "Developer Name".to_string(),
                state: PluginState::Loaded,
                health: PluginHealth::Healthy,
                actions: vec!["MyAction".to_string()],
                functions: vec!["myFunction".to_string()],
                dependencies: vec![],
            },
        }
    }
}

impl RulePlugin for MyCustomPlugin {
    fn get_metadata(&self) -> &PluginMetadata {
        &self.metadata
    }

    fn register_actions(&self, engine: &mut RustRuleEngine) -> Result<()> {
        engine.register_action_handler("MyAction", |params, facts| {
            // Your custom action logic here
            Ok(())
        });
        Ok(())
    }

    fn register_functions(&self, engine: &mut RustRuleEngine) -> Result<()> {
        engine.register_function("myFunction", |args, _facts| {
            // Your custom function logic here
            Ok(Value::String("result".to_string()))
        });
        Ok(())
    }

    fn unload(&mut self) -> Result<()> {
        self.metadata.state = PluginState::Unloaded;
        Ok(())
    }

    fn health_check(&mut self) -> PluginHealth {
        PluginHealth::Healthy
    }
}

🎯 Advanced Features

Knowledge Base Management

let mut kb = KnowledgeBase::new("Advanced");

// Add rules with different salience (priority)
kb.add_rule_from_grl(r#"
rule "HighPriority" salience 100 { when condition then action }
"#)?;

kb.add_rule_from_grl(r#"
rule "LowPriority" salience 10 { when condition then action }
"#)?;

// Rules execute in salience order (highest first)
let mut engine = RustRuleEngine::new(kb);

Complex Data Objects

use std::collections::HashMap;

let mut facts = Facts::new();

// Nested object structures
let mut customer = HashMap::new();
customer.insert("name".to_string(), Value::String("John Doe".to_string()));
customer.insert("age".to_string(), Value::Integer(30));

let mut address = HashMap::new();
address.insert("country".to_string(), Value::String("US".to_string()));
address.insert("state".to_string(), Value::String("CA".to_string()));

customer.insert("address".to_string(), Value::Object(address));
facts.set("Customer".to_string(), Value::Object(customer));

// Access nested properties in rules
let rule = r#"
rule "LocationRule" {
    when
        Customer.address.country == "US" &&
        Customer.address.state == "CA" &&
        Customer.age >= 21
    then
        Customer.eligible = true;
        Customer.discount = 0.1;
}
"#;

Method Calls and Functions

// Built-in functions in conditions
let rule = r#"
rule "ValidationRule" {
    when
        isEmail(Customer.email) == true &&
        length(Customer.name) > 2 &&
        inRange(Customer.age, 18, 120) == true
    then
        Customer.validated = true;
}
"#;

// Custom function registration
engine.register_function("customValidation", |args, facts| {
    // Custom validation logic
    Ok(Value::Boolean(true))
});

Error Handling and Debugging

use rust_rule_engine::errors::{Result, RuleEngineError};

// Comprehensive error handling
match engine.execute(&facts) {
    Ok(result) => {
        println!("Success: {} rules executed", result.rules_executed);
        println!("Execution time: {:?}", result.execution_time);
    },
    Err(RuleEngineError::ParseError { message, line, column }) => {
        eprintln!("Parse error at {}:{} - {}", line, column, message);
    },
    Err(RuleEngineError::EvaluationError { message }) => {
        eprintln!("Evaluation error: {}", message);
    },
    Err(e) => {
        eprintln!("Other error: {}", e);
    }
}

📚 Examples

The repository includes comprehensive examples:

• Basic Usage: examples/basic_demo.rs
• Plugin System: examples/builtin_plugins_demo.rs
• E-commerce Rules: examples/ecommerce.rs
• Fraud Detection: examples/fraud_detection.rs
• GRL Compatibility: examples/grule_demo.rs
• Streaming Data: examples/realtime_trading_stream.rs

Run examples:

cargo run --example builtin_plugins_demo
cargo run --example ecommerce
cargo run --example fraud_detection

🔧 Configuration

Engine Configuration

use rust_rule_engine::engine::engine::EngineConfig;

let config = EngineConfig {
    max_cycles: 1000,
    enable_tracing: true,
    parallel_execution: true,
    cycle_detection: true,
};

let engine = RustRuleEngine::with_config(kb, config);

Plugin Configuration

use rust_rule_engine::engine::plugin::{PluginConfig, PluginManager};

let plugin_config = PluginConfig {
    max_plugins: 50,
    enable_hot_reload: true,
    plugin_timeout_ms: 5000,
    safety_checks: true,
};

let plugin_manager = PluginManager::new(plugin_config);

🚀 Performance

Rust Rule Engine v0.9.0 is designed for high-performance scenarios:

• Zero-copy: Efficient memory usage with minimal allocations
• Parallel Execution: Multi-threaded rule processing when safe
• Optimized Parsing: Fast GRL parsing with minimal overhead
• Plugin Caching: Efficient plugin management and reuse
• Cycle Detection: Prevents infinite loops in rule chains

🗺 Roadmap

v0.10.0 (Planned)

• Advanced Plugin Features
  • Plugin dependency management
  • Plugin versioning and compatibility
  • Plugin marketplace integration
• Performance Enhancements
  • Rule compilation to bytecode
  • Advanced caching strategies
  • Memory pool optimization
• Developer Experience
  • Visual rule debugger
  • Rule testing framework
  • IDE plugins and syntax highlighting

v1.0.0 (Future)

• Production Features
  • Distributed rule execution
  • Rule versioning and migration
  • Advanced monitoring and metrics
• Enterprise Features
  • Role-based access control
  • Audit logging
  • Integration with external systems

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/KSD-CO/rust-rule-engine.git
cd rust-rule-engine
cargo build
cargo test
cargo run --example builtin_plugins_demo

Running Tests

# Run all tests
cargo test

# Run with coverage
cargo test --features coverage

# Run benchmarks
cargo bench

📄 License

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

🙏 Acknowledgments

• Inspired by Grule rule engine
• Built with Rust's powerful type system and performance capabilities
• Community feedback and contributions

📞 Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email: tonthatvu.hust@gmail.com

---

Rust Rule Engine v0.9.0 - Powerful, extensible, and production-ready rule engine for Rust 🦀⚡

• 🌊 Stream Processing: Real-time event processing with time windows (optional)
• 📊 Analytics: Built-in aggregations and trend analysis
• 🚨 Action Handlers: Custom action execution for external system integration
• 📈 Advanced Analytics: Production-ready performance monitoring and optimization insights

🌊 Advanced Workflow Engine v0.8.0 (Latest!)

The rule engine now features a comprehensive workflow engine with agenda group management, scheduled task execution, and real-time workflow state tracking for complex business process automation.

Workflow Features

• 📋 Agenda Group Management: Organize rules into execution phases with automatic transitions
• ⏰ Scheduled Task System: Time-based task execution with flexible scheduling
• 🔄 Workflow State Tracking: Real-time workflow monitoring and progress tracking
• 🎯 Dynamic Rule Activation: Context-aware rule execution based on workflow state
• � Comprehensive Analytics: Detailed workflow performance metrics and insights

Workflow Example

use rust_rule_engine::engine::{RustRuleEngine, EngineConfig};
use rust_rule_engine::engine::knowledge_base::KnowledgeBase;
use rust_rule_engine::parser::grl::GRLParser;
use rust_rule_engine::types::Value;
use rust_rule_engine::Facts;

// Create workflow engine
let config = EngineConfig {
    debug_mode: false,
    max_cycles: 100,
    enable_stats: true,
    ..Default::default()
};
let mut engine = RustRuleEngine::with_config(KnowledgeBase::new("WorkflowDemo"), config);

// Define workflow rules with agenda groups
let workflow_rules = vec![
    r#"
    rule "StartOrderWorkflow" salience 100 agenda-group "start" {
        when Order.Status == "pending"
        then
            log("🔄 Starting order processing workflow");
            ActivateAgendaGroup("validation");
            SetWorkflowData("order-process", status="started");
    }
    "#,
    r#"
    rule "ValidateOrder" salience 90 agenda-group "validation" {
        when Order.Amount > 0 && Inventory.Available == true
        then
            log("✅ Order validation passed");
            Order.Status = "validated";
            ActivateAgendaGroup("payment");
    }
    "#,
    r#"
    rule "ProcessVIPPayment" salience 80 agenda-group "payment" {
        when Order.Status == "validated" && Customer.VIP == true
        then
            log("💳 Processing VIP payment with priority");
            Order.Status = "paid";
            ActivateAgendaGroup("fulfillment");
    }
    "#
];

// Execute workflow with automatic agenda management
let result = engine.execute_workflow(&facts)?;
println!("Workflow completed: {} rules fired in {} cycles", 
         result.rules_fired, result.cycles);

🚨 Advanced Action Handlers v0.7.1

The rule engine now supports advanced custom action execution with simplified parameter syntax and automatic fact resolution, enabling seamless integration with external systems.

Action Handler System

Register custom handlers for ActionType::Custom actions that can execute real business logic instead of just debug printing.

✨ Simplified Parameter Syntax v0.7.1

use rust_rule_engine::engine::{RustRuleEngine, EngineConfig};
use rust_rule_engine::types::Value;
use std::collections::HashMap;

// Create engine
let mut engine = RustRuleEngine::with_config(kb, EngineConfig::default());

// Register email handler with indexed parameters
engine.register_action_handler("SendEmail", |params, facts| {
    // Access parameters by index: "0", "1", "2"...
    let to = if let Some(arg) = params.get("0") {
        match arg {
            Value::String(s) => {
                // Automatic fact resolution: Customer.email → alice@example.com
                if let Some(resolved) = facts.get_nested(s) {
                    resolved.to_string()
                } else {
                    s.clone()
                }
            }
            _ => arg.to_string(),
        }
    } else {
        "unknown@example.com".to_string()
    };
    
    let subject = params.get("1").map(|v| v.to_string()).unwrap_or("No Subject".to_string());
    let body = params.get("2").map(|v| v.to_string()).unwrap_or("No Body".to_string());
    
    // Execute actual email sending logic
    println!("📧 EMAIL SENT:");
    println!("   To: {}", to);
    println!("   Subject: {}", subject);
    println!("   Body: {}", body);
    
    Ok(())
});

// Register database logger with simplified syntax
engine.register_action_handler("LogToDatabase", |params, facts| {
    let table = params.get("0").map(|v| v.to_string()).unwrap_or("default_table".to_string());
    let event = params.get("1").map(|v| v.to_string()).unwrap_or("unknown_event".to_string());
    
    println!("🗄️ DATABASE LOG:");
    println!("   Table: {}", table);
    println!("   Event: {}", event);
    println!("   Timestamp: {}", chrono::Utc::now().format("%Y-%m-%d %H:%M:%S"));
    
    Ok(())
});

Parameter Resolution

Action handlers automatically resolve fact references in parameters:

// In GRL rule:
rule "WelcomeCustomer" {
    when
        Customer.status == "new"
    then
        SendEmail(Customer.email, "Welcome!", Customer.name);
}

// Parameter resolution in action:
// Parameter 0: "Customer.email" → "john.doe@example.com"
// Parameter 1: "Welcome!" → "Welcome!"
// Parameter 2: "Customer.name" → "John Doe"

GRL Usage with Action Handlers

rule "VIPCustomerWelcome" salience 20 no-loop {
    when
        Customer.tier == "VIP" && Customer.welcome_sent != true
    then
        SendEmail(Customer.email, "VIP Welcome Package", "Welcome to our VIP program!");
        LogToDatabase("customer_events", "vip_welcome_sent");
        Customer.welcome_sent = true;
}

rule "HighValueOrderAlert" salience 15 no-loop {
    when
        Order.total > 5000 && Order.alert_sent != true
    then
        SendAlert("HIGH", "High-value order requires review");
        ProcessPayment(Order.total, "secure_processing");
        Order.alert_sent = true;
}

Action Handler Examples

See complete examples:

• Action Handlers Demo - Comprehensive action handler showcase

Benefits

✅ External System Integration: Connect rules to emails, databases, APIs, services
✅ Real Business Logic: Execute actual business operations, not just debug prints
✅ Parameter Resolution: Automatic fact value substitution in action parameters
✅ Facts Integration: Full access to rule engine fact data within handlers
✅ Error Handling: Graceful failure handling with meaningful error messages
✅ Performance: Efficient execution with minimal overhead
✅ Flexibility: Register any custom business logic as action handlers
✅ Testability: Mock handlers for unit testing rule behavior

🧩 Advanced Pattern Matching v0.7.0

The rule engine now supports advanced pattern matching capabilities similar to Drools, enabling complex conditional logic with EXISTS, NOT, and FORALL patterns.

Pattern Types

EXISTS Pattern

Check if at least one fact matches the condition:

// Programmatic API
let condition = ConditionGroup::exists(
    ConditionGroup::Single(Condition::new(
        "Customer.tier".to_string(),
        Operator::Equal,
        Value::String("VIP".to_string()),
    ))
);

// GRL Syntax
rule "ActivateVIPService" salience 20 {
    when
        exists(Customer.tier == "VIP")
    then
        System.vipServiceActive = true;
        log("VIP service activated");
}

NOT Pattern

Check if no facts match the condition:

// Programmatic API
let condition = ConditionGroup::not(
    ConditionGroup::exists(
        ConditionGroup::Single(Condition::new(
            "Order.status".to_string(),
            Operator::Equal,
            Value::String("pending".to_string()),
        ))
    )
);

// GRL Syntax
rule "SendMarketingEmail" salience 15 {
    when
        !exists(Order.status == "pending")
    then
        Marketing.emailSent = true;
        log("Marketing email sent - no pending orders");
}

FORALL Pattern

Check if all facts of a type match the condition:

// Programmatic API  
let condition = ConditionGroup::forall(
    ConditionGroup::Single(Condition::new(
        "Order.status".to_string(),
        Operator::Equal,
        Value::String("processed".to_string()),
    ))
);

// GRL Syntax
rule "EnableShipping" salience 10 {
    when
        forall(Order.status == "processed")
    then
        Shipping.enabled = true;
        log("All orders processed - shipping enabled");
}

Combined Patterns

Combine multiple patterns with logical operators:

rule "ComplexBusinessRule" salience 25 {
    when
        exists(Customer.tier == "VIP") && 
        !exists(Alert.priority == "high") &&
        forall(Order.status == "processed")
    then
        System.premiumModeEnabled = true;
        log("Premium mode activated - all conditions met");
}

Pattern Matching Examples

See complete examples:

• Pattern Matching Demo - Programmatic API
• GRL Pattern Matching Demo - GRL file syntax
• Complex Patterns from File - Advanced GRL patterns

Drools Compatibility

Pattern matching brings ~85% compatibility with Drools rule engine, supporting the core pattern matching features that enable complex business logic modeling.

🎯 Rule Attributes v0.6.0

Advanced rule attributes providing Drools-compatible workflow control and execution management:

📋 Agenda Groups - Workflow Control

Organize rules into execution phases with agenda group control:

rule "ValidateCustomer" agenda-group "validation" salience 10 {
    when
        Customer.age >= 18
    then
        Customer.status = "valid";
        log("Customer validated");
}

rule "ProcessPayment" agenda-group "processing" salience 5 {
    when
        Customer.status == "valid"
    then
        Order.status = "processed";
        log("Payment processed");
}

// Control workflow execution
engine.set_agenda_focus("validation");
engine.execute(&facts)?; // Only validation rules fire

engine.set_agenda_focus("processing"); 
engine.execute(&facts)?; // Only processing rules fire

🎯 Activation Groups - Mutually Exclusive Rules

Ensure only one rule from a group fires:

rule "PremiumDiscount" activation-group "discount" salience 10 {
    when Customer.tier == "premium"
    then Order.discount = 0.20;
}

rule "GoldDiscount" activation-group "discount" salience 8 {
    when Customer.tier == "gold"  
    then Order.discount = 0.15;
}

🔒 Lock-on-Active - One-time Execution

Prevent rules from firing again until agenda group changes:

rule "WelcomeEmail" lock-on-active salience 10 {
    when Customer.isNew == true
    then sendWelcomeEmail(Customer);
}

⏰ Date Effective/Expires - Time-based Rules

Create seasonal or time-limited rules:

rule "ChristmasDiscount" 
    date-effective "2025-12-01T00:00:00Z"
    date-expires "2025-12-31T23:59:59Z" 
    salience 20 {
    when Order.total > 100
    then Order.seasonalDiscount = 0.25;
}

🔄 Combined Attributes - Complex Rules

Mix multiple attributes for sophisticated control:

rule "ComplexPaymentRule"
    agenda-group "processing"
    activation-group "payment"
    lock-on-active
    no-loop
    salience 30 {
    when
        Order.status == "pending" && Payment.method == "credit"
    then
        Order.status = "processed";
        Payment.confirmed = true;
}

📊 Programmatic API

Use attributes with the Rust API:

let rule = Rule::new("MyRule", conditions, actions)
    .with_agenda_group("validation".to_string())
    .with_activation_group("discount".to_string())
    .with_lock_on_active(true)
    .with_date_effective_str("2025-12-01T00:00:00Z")?
    .with_date_expires_str("2025-12-31T23:59:59Z")?;

// Get available groups
let agenda_groups = engine.get_agenda_groups();
let activation_groups = engine.get_activation_groups();

// Workflow control
engine.set_agenda_focus("validation");
engine.execute(&facts)?;

🤖 AI Integration (NEW!)

Integrate AI/ML models seamlessly into your rules, similar to Drools Pragmatic AI:

Features

• 🤖 Sentiment Analysis: Real-time text sentiment evaluation
• 🛡️ Fraud Detection: ML-powered fraud scoring and detection
• 🏆 Predictive Analytics: Customer tier prediction and scoring
• 🧠 LLM Reasoning: Large Language Model decision support
• 📊 Real-time ML Scoring: Dynamic model inference in rules

Example AI Rules

rule "AI Customer Service" salience 100 {
    when
        CustomerMessage.type == "complaint"
    then
        analyzeSentiment(CustomerMessage.text);
        set(Ticket.priority, "high");
        logMessage("🤖 AI analyzing customer sentiment");
}

rule "AI Fraud Detection" salience 90 {
    when
        Transaction.amount > 1000
    then
        detectFraud(Transaction.amount, Transaction.userId);
        set(Transaction.status, "under_review");
        sendNotification("🛡️ Checking for potential fraud", "security@company.com");
}

rule "AI Tier Prediction" salience 80 {
    when
        Customer.tier == "pending"
    then
        predictTier(Customer.id);
        set(Customer.tierAssignedBy, "AI");
        logMessage("🏆 AI predicting customer tier");
}

Register AI Functions

// Register AI-powered functions
engine.register_function("analyzeSentiment", |args, _facts| {
    let text = args[0].as_string().unwrap_or("".to_string());
    
    // Call actual AI API (OpenAI, Anthropic, Hugging Face, etc.)
    let rt = tokio::runtime::Runtime::new().unwrap();
    let sentiment = rt.block_on(async {
        call_openai_sentiment_api(&text).await
    }).unwrap_or_else(|_| "neutral".to_string());
    
    Ok(Value::String(sentiment))
});

engine.register_function("detectFraud", |args, facts| {
    let amount = args[0].as_number().unwrap_or(0.0);
    let user_id = args[1].as_string().unwrap_or("unknown".to_string());
    
    // Call actual ML fraud detection API
    let rt = tokio::runtime::Runtime::new().unwrap();
    let is_fraud = rt.block_on(async {
        call_fraud_detection_api(amount, &user_id, facts).await
    }).unwrap_or_else(|_| false);
    
    Ok(Value::Boolean(is_fraud))
});

engine.register_function("predictTier", |args, facts| {
    let customer_id = args[0].as_string().unwrap_or("unknown".to_string());
    
    // Call actual ML tier prediction API
    let rt = tokio::runtime::Runtime::new().unwrap();
    let predicted_tier = rt.block_on(async {
        call_tier_prediction_api(&customer_id, facts).await
    }).unwrap_or_else(|_| "bronze".to_string());
    
    Ok(Value::String(predicted_tier))
});

📋 Changelog

v0.8.0 (October 2025) - Advanced Workflow Engine Implementation 🌊

• 🌊 Advanced Workflow Engine: Complete workflow management system with comprehensive features
  • 📋 Agenda Group Management: Organize rules into execution phases with automatic focus transitions
  • ⏰ Scheduled Task System: Time-based task execution with flexible scheduling and conditional triggers
  • 🔄 Workflow State Tracking: Real-time workflow monitoring with start/complete lifecycle management
  • 🎯 Dynamic Agenda Activation: Context-aware agenda group activation based on workflow state
  • 📊 Workflow Analytics: Detailed performance metrics including execution statistics and task monitoring
  • 🚀 Seamless Integration: Unified API combining rule execution with workflow orchestration
• 🔧 Enhanced Rule Engine: Improved fact handling and condition evaluation
  • Facts API Enhancement: Extended Facts system with workflow data integration
  • Condition Evaluation: Optimized condition processing with better error handling
  • Action Processing: Enhanced action execution with workflow context awareness
• 🧪 Comprehensive Demos: Real-world workflow examples
  • Basic order processing workflow with VIP customer routing
  • Advanced workflow with scheduled tasks and multi-phase execution
  • Complete workflow lifecycle demonstrations with detailed logging
• 🛡️ Production Ready: Enhanced error handling and performance optimization for workflow scenarios

v0.7.1 (October 2025) - Advanced Action Handlers Implementation 🚨

• 🚨 Advanced Action Handlers: Custom action execution system for external integrations
  • Action Handler Registry: Register custom handlers for ActionType::Custom execution
  • Parameter Resolution: Automatic fact value substitution in action parameters
  • Facts Integration: Full access to fact data within action handlers
  • Error Handling: Graceful failure handling with meaningful error messages
  • Built-in Handler Examples: Email, database logging, alerts, payment processing
• 🔧 Enhanced Custom Actions: Fix ActionType::Custom from debug-only to fully functional
  • Previously: ActionType::Custom only printed debug messages
  • Now: Executes registered business logic handlers with real functionality
• ⚡ Parameter Resolution Engine: Smart fact reference resolution in action parameters
  • "Customer.email" → resolves to actual email value from facts
  • "Order.total" → resolves to actual order total amount
  • Supports nested fact path resolution with dot notation
• 🧪 Comprehensive Demo: Real-world action handler examples
  • Email sending with template parameters
  • Database event logging with fact context
  • Multi-level alert system (INFO, HIGH, CRITICAL)
  • Payment processing with business rule validation
• 🛡️ No-Loop Protection: Enhanced rule execution control for action-triggered rules

v0.7.0 (October 2025) - Advanced Pattern Matching & Drools Compatibility 🧩

• 🧩 Advanced Pattern Matching: Complete implementation of EXISTS, NOT, and FORALL patterns
  • EXISTS pattern: Check if at least one fact matches condition
  • NOT pattern: Check if no facts match condition (using !exists(...))
  • FORALL pattern: Check if all facts of a type match condition
  • Complex patterns: Combine patterns with logical operators (AND, OR, NOT)
• 🎯 GRL Syntax Support: Full pattern matching support in GRL files
  • exists(Customer.tier == "VIP") syntax for existence checking
  • !exists(Order.status == "pending") syntax for non-existence
  • forall(Order.status == "processed") syntax for universal quantification
  • Combined patterns: exists(...) && !exists(...) && forall(...)
• 🔧 Parser Extensions: Enhanced GRL parser with pattern matching keywords
  • Recursive pattern parsing with proper parentheses handling
  • Seamless integration with existing logical operators
  • Comprehensive parser tests for all pattern types
• ⚡ Pattern Evaluation Engine: High-performance pattern matching evaluation
  • Smart fact type detection and mapping (e.g., Customer1 → Customer)
  • Efficient fact iteration and filtering algorithms
  • Full backward compatibility with existing rule engine
• 🧪 Comprehensive Testing: Full test coverage for pattern matching features
  • 4 dedicated pattern matcher unit tests (all passing)
  • Real-world business scenario demonstrations
  • GRL file parsing and execution integration tests
  • Multiple example files showcasing pattern matching capabilities

v0.6.0 (October 2025) - Rule Attributes Enhancement 🎯

• 🎯 Comprehensive Rule Attributes: Drools-compatible rule attributes system
  • 📋 Agenda Groups: Structured workflow control with focus management
  • 🔒 Activation Groups: Mutually exclusive rule execution with salience priority
  • 🔒 Lock-on-Active: Prevent rules from firing multiple times per agenda activation
  • ⏰ Date Effective/Expires: Time-based rule activation with DateTime support
  • 📊 Programmatic API: Full Rust API for attribute management
• 🔧 Enhanced GRL Parser: Support for flexible rule attribute syntax in any position
• 🧪 Comprehensive Testing: 27/27 unit tests including new agenda management tests
• 📚 Complete Demo: Full demonstration of all 4 attribute features
• ⚡ Performance Optimized: Efficient agenda focus stack and activation group management

v0.5.0 (October 2025) - AI Integration 🤖

• 🤖 AI-Powered Rules: Built-in support for AI/ML model integration
  • Sentiment analysis functions for customer service automation
  • ML-powered fraud detection with real-time risk scoring
  • Predictive analytics for customer tier assignment
  • LLM reasoning for complex business decision support
  • Real-time ML scoring for dynamic pricing and recommendations
• 🧠 AI Function Registry: Easy registration and management of AI model functions
• 🚀 Production AI Examples: Complete examples with simulated AI APIs
• 📊 AI Insights: Track AI model performance and decision outcomes
• 🌐 AI-Enhanced REST API: HTTP endpoints for AI-powered rule execution

v0.4.1 (October 2025) - Enhanced Parser & Publishing

• 🔧 Enhanced GRL Parser: Improved parsing with complex nested conditions
  • Support for parentheses grouping: (age >= 18) && (status == "active")
  • Better handling of compound boolean expressions
  • Improved error messages and validation
• 📦 Published to Crates.io: Available as rust-rule-engine = "0.4.1"
• 📚 Comprehensive Examples: Added 40+ examples covering all features
• 📖 Complete Documentation: Full API documentation and usage guides

v0.3.1 (October 2025) - REST API with Monitoring

• 🌐 Production REST API: Complete web API with advanced analytics integration
  • Comprehensive endpoints for rule execution and monitoring
  • Real-time analytics dashboard with performance insights
  • Health monitoring and system status endpoints
  • CORS support and proper error handling
  • Sample requests and complete API documentation
  • Production-ready demo script for testing

v0.3.0 (October 2025) - AST-Based Dependency Analysis & Advanced Analytics

🚀 Quick Start

Add to your Cargo.toml:

[dependencies]
rust-rule-engine = "0.8.0"
chrono = "0.4"  # For date-based rule attributes

# For streaming features (optional)
rust-rule-engine = { version = "0.8.0", features = ["streaming"] }

📄 File-Based Rules

Create a rule file rules/example.grl:

rule "AgeCheck" salience 10 {
    when
        User.Age >= 18 && User.Country == "US"
    then
        User.setIsAdult(true);
        User.setCategory("Adult");
        log("User qualified as adult");
}

rule "VIPUpgrade" salience 20 {
    when
        User.IsAdult == true && User.SpendingTotal > 1000.0
    then
        User.setIsVIP(true);
        log("User upgraded to VIP status");
}

use rust_rule_engine::{RuleEngineBuilder, Value, Facts};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create engine with rule file
    let mut engine = RuleEngineBuilder::new()
        .with_rule_file("rules/example.grl")?
        .build();

    // Register custom functions
    engine.register_function("User.setIsAdult", |args, _| {
        println!("Setting adult status: {:?}", args[0]);
        Ok(Value::Boolean(true))
    });

    engine.register_function("User.setCategory", |args, _| {
        println!("Setting category: {:?}", args[0]);
        Ok(Value::String(args[0].to_string()))
    });

    // Create facts
    let facts = Facts::new();
    let mut user = HashMap::new();
    user.insert("Age".to_string(), Value::Integer(25));
    user.insert("Country".to_string(), Value::String("US".to_string()));
    user.insert("SpendingTotal".to_string(), Value::Number(1500.0));

    facts.add_value("User", Value::Object(user))?;

    // Execute rules
    let result = engine.execute(&facts)?;
    println!("Rules fired: {}", result.rules_fired);

    Ok(())
}

📝 Inline String Rules

Define rules directly in your code:

use rust_rule_engine::{RuleEngineBuilder, Value, Facts};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let grl_rules = r#"
        rule "HighValueCustomer" salience 20 {
            when
                Customer.TotalSpent > 1000.0
            then
                sendWelcomeEmail(Customer.Email, "GOLD");
                log("Customer upgraded to GOLD tier");
        }

        rule "LoyaltyBonus" salience 15 {
            when
                Customer.OrderCount >= 10
            then
                applyLoyaltyBonus(Customer.Id, 50.0);
                log("Loyalty bonus applied");
        }
    "#;

    // Create engine with inline rules
    let mut engine = RuleEngineBuilder::new()
        .with_inline_grl(grl_rules)?
        .build();

    // Register custom functions
    engine.register_function("sendWelcomeEmail", |args, _| {
        println!("📧 Welcome email sent to {:?} for {:?} tier", args[0], args[1]);
        Ok(Value::Boolean(true))
    });

    engine.register_function("applyLoyaltyBonus", |args, _| {
        println!("💰 Loyalty bonus of {:?} applied to customer {:?}", args[1], args[0]);
        Ok(Value::Number(args[1].as_number().unwrap_or(0.0)))
    });

    // Create facts
    let facts = Facts::new();
    let mut customer = HashMap::new();
    customer.insert("TotalSpent".to_string(), Value::Number(1250.0));
    customer.insert("OrderCount".to_string(), Value::Integer(12));
    customer.insert("Email".to_string(), Value::String("john@example.com".to_string()));
    customer.insert("Id".to_string(), Value::String("CUST001".to_string()));

    facts.add_value("Customer", Value::Object(customer))?;

    // Execute rules
    let result = engine.execute(&facts)?;
    println!("Rules fired: {}", result.rules_fired);

    Ok(())
}

🎯 Rule Attributes Quick Example

Experience the power of Rule Attributes v0.6.0 with workflow control:

use rust_rule_engine::{RuleEngineBuilder, Value, Facts};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let attribute_rules = r#"
        rule "ValidateAge" agenda-group "validation" salience 10 {
            when
                User.age >= 18
            then
                User.status = "valid";
                log("Age validation passed");
        }

        rule "ProcessPayment" agenda-group "processing" salience 10 {
            when
                User.status == "valid"
            then
                Order.status = "processed";
                log("Payment processed");
        }

        rule "PremiumDiscount" activation-group "discount" salience 10 {
            when Customer.tier == "premium"
            then Order.discount = 0.20;
        }

        rule "GoldDiscount" activation-group "discount" salience 8 {
            when Customer.tier == "gold"
            then Order.discount = 0.15;
        }

        rule "WelcomeEmail" lock-on-active salience 15 {
            when Customer.isNew == true
            then sendWelcomeEmail(Customer.email);
        }
    "#;

    // Create engine with attribute rules
    let mut engine = RuleEngineBuilder::new()
        .with_inline_grl(attribute_rules)?
        .build();

    // Create facts
    let facts = Facts::new();
    
    // Add user data
    let mut user = HashMap::new();
    user.insert("age".to_string(), Value::Integer(25));
    user.insert("status".to_string(), Value::String("pending".to_string()));
    facts.add_value("User", Value::Object(user))?;

    let mut customer = HashMap::new();
    customer.insert("tier".to_string(), Value::String("premium".to_string()));
    customer.insert("isNew".to_string(), Value::Boolean(true));
    customer.insert("email".to_string(), Value::String("user@example.com".to_string()));
    facts.add_value("Customer", Value::Object(customer))?;

    let mut order = HashMap::new();
    order.insert("status".to_string(), Value::String("pending".to_string()));
    order.insert("discount".to_string(), Value::Number(0.0));
    facts.add_value("Order", Value::Object(order))?;

    // 🔍 Phase 1: Validation workflow
    engine.set_agenda_focus("validation");
    let result1 = engine.execute(&facts)?;
    println!("✅ Validation phase: {} rules fired", result1.rules_fired);

    // ⚙️ Phase 2: Processing workflow  
    engine.set_agenda_focus("processing");
    let result2 = engine.execute(&facts)?;
    println!("🔄 Processing phase: {} rules fired", result2.rules_fired);

    // 🎯 Phase 3: Discount (only ONE rule fires due to activation-group)
    engine.set_agenda_focus("MAIN"); // Default group
    let result3 = engine.execute(&facts)?;
    println!("💰 Discount phase: {} rules fired (mutually exclusive)", result3.rules_fired);

    Ok(())
}

🎨 Visual Rule Builder (NEW!)

Create rules visually with our drag-and-drop interface!

🌐 Visual Rule Builder - Build GRL rules without coding!

✨ Features

• 🎯 Drag & Drop Interface: Intuitive visual rule creation
• 📝 Real-time GRL Generation: See your rules as GRL code instantly
• 🔍 Syntax Validation: Automatic validation and error checking
• 📋 Template Library: Pre-built rule templates for common scenarios
• 💾 Export & Import: Save and load your rule configurations
• 🚀 One-Click Integration: Copy-paste generated GRL directly into your Rust projects

🎮 Quick Demo

1. Visit: https://visual-rule-builder.amalthea.cloud/
2. Build: Drag conditions and actions to create your business logic
3. Generate: Get clean, optimized GRL code automatically
4. Integrate: Copy the GRL into your Rust Rule Engine project

📚 Perfect For

• 🎓 Learning: Understand rule structure and syntax visually
• ⚡ Rapid Prototyping: Quickly build and test rule logic
• 👥 Business Users: Create rules without programming knowledge
• 🔧 Complex Rules: Visualize intricate business logic flows

💡 Example Workflow

// Generated from Visual Builder
rule "CustomerUpgrade" salience 20 {
    when
        Customer.totalSpent > 1000.0 && 
        Customer.loyaltyYears >= 2 &&
        !exists(Customer.tier == "VIP")
    then
        Customer.tier = "VIP";
        sendWelcomePackage(Customer.email);
        log("Customer upgraded to VIP status");
}

Try it now: Build this rule visually in under 2 minutes! 🚀

---

🤖 Complete AI Integration Example

Here's a complete example showing how to build an AI-powered business rule system:

use rust_rule_engine::{RuleEngineBuilder, Value, Facts};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ai_rules = r#"
        rule "AI Customer Service" salience 100 {
            when
                CustomerMessage.type == "complaint"
            then
                analyzeSentiment(CustomerMessage.text);
                set(Ticket.priority, "high");
                logMessage("🤖 AI analyzing customer sentiment");
        }

        rule "AI Fraud Detection" salience 90 {
            when
                Transaction.amount > 1000
            then
                detectFraud(Transaction.amount, Transaction.userId);
                set(Transaction.status, "under_review");
                sendNotification("🛡️ Checking for potential fraud", "security@company.com");
        }

        rule "AI Tier Prediction" salience 80 {
            when
                Customer.tier == "pending"
            then
                predictTier(Customer.id);
                set(Customer.tierAssignedBy, "AI");
                logMessage("🏆 AI predicting customer tier");
        }

        rule "LLM Decision Support" salience 70 {
            when
                Customer.needsReview == true
            then
                askLLM("Should we approve this customer for premium tier?", Customer.id);
                set(Customer.reviewedBy, "AI-LLM");
                logMessage("🧠 LLM analyzing customer for approval");
        }

        rule "ML Dynamic Pricing" salience 60 {
            when
                Product.category == "dynamic" && Customer.tier != "unknown"
            then
                calculateMLPrice(Product.basePrice, Customer.tier, Product.demand);
                set(Product.priceSource, "ML");
                logMessage("📊 ML calculating dynamic price");
        }
    "#;

    let mut engine = RuleEngineBuilder::new()
        .with_inline_grl(ai_rules)?
        .with_max_cycles(5)
        .build();

    // Register AI functions (in production, these would call real AI APIs)
    engine.register_function("analyzeSentiment", |args, facts| {
        let text = args[0].as_string().unwrap_or("".to_string());
        
        // Simulate sentiment analysis (OpenAI, Anthropic, HuggingFace, etc.)
        let sentiment = if text.contains("terrible") || text.contains("awful") {
            "negative"
        } else if text.contains("love") || text.contains("great") {
            "positive"
        } else {
            "neutral"
        };
        
        // Store result in facts for other rules
        facts.set_value("Analysis.sentiment", Value::String(sentiment.to_string()))?;
        
        println!("🤖 Sentiment Analysis: '{}' → {}", text, sentiment);
        Ok(Value::String(sentiment.to_string()))
    });

    engine.register_function("detectFraud", |args, facts| {
        let amount = args[0].as_number().unwrap_or(0.0);
        let user_id = args[1].as_string().unwrap_or("unknown".to_string());
        
        // Simulate ML fraud detection model
        let risk_score = if amount > 5000.0 { 0.95 } else if amount > 2000.0 { 0.75 } else { 0.2 };
        let is_fraud = risk_score > 0.8;
        
        facts.set_value("FraudCheck.riskScore", Value::Number(risk_score))?;
        facts.set_value("FraudCheck.isFraud", Value::Boolean(is_fraud))?;
        
        println!("🛡️ Fraud Detection: Amount {} for user {} → Risk: {:.2}, Fraud: {}", 
                amount, user_id, risk_score, is_fraud);
        
        Ok(Value::Boolean(is_fraud))
    });

    engine.register_function("predictTier", |args, facts| {
        let customer_id = args[0].as_string().unwrap_or("unknown".to_string());
        
        // Simulate customer tier prediction model
        let predicted_tiers = ["bronze", "silver", "gold", "platinum"];
        let tier = predicted_tiers[customer_id.len() % predicted_tiers.len()];
        
        facts.set_value("TierPrediction.tier", Value::String(tier.to_string()))?;
        facts.set_value("TierPrediction.confidence", Value::Number(0.87))?;
        
        println!("🏆 Tier Prediction: Customer {} → {} tier (87% confidence)", customer_id, tier);
        Ok(Value::String(tier.to_string()))
    });

    engine.register_function("askLLM", |args, facts| {
        let question = args[0].as_string().unwrap_or("".to_string());
        let customer_id = args[1].as_string().unwrap_or("unknown".to_string());
        
        // Simulate LLM reasoning (GPT-4, Claude, etc.)
        let decision = if customer_id.contains("VIP") { "approve" } else { "review_further" };
        let reasoning = format!("Based on customer profile analysis, recommendation: {}", decision);
        
        facts.set_value("LLMDecision.result", Value::String(decision.to_string()))?;
        facts.set_value("LLMDecision.reasoning", Value::String(reasoning.clone()))?;
        
        println!("🧠 LLM Analysis: {} → {}", question, reasoning);
        Ok(Value::String(decision.to_string()))
    });

    engine.register_function("calculateMLPrice", |args, facts| {
        let base_price = args[0].as_number().unwrap_or(100.0);
        let tier = args[1].as_string().unwrap_or("bronze".to_string());
        let demand = args[2].as_number().unwrap_or(1.0);
        
        // Simulate ML pricing model
        let tier_multiplier = match tier.as_str() {
            "platinum" => 0.8,
            "gold" => 0.9,
            "silver" => 0.95,
            _ => 1.0,
        };
        
        let dynamic_price = base_price * tier_multiplier * demand;
        
        facts.set_value("Pricing.dynamicPrice", Value::Number(dynamic_price))?;
        facts.set_value("Pricing.discount", Value::Number((1.0 - tier_multiplier) * 100.0))?;
        
        println!("📊 ML Pricing: Base ${:.2} × {} tier × {:.1}x demand → ${:.2}", 
                base_price, tier, demand, dynamic_price);
        
        Ok(Value::Number(dynamic_price))
    });

    // Helper functions
    engine.register_function("set", |args, facts| {
        if args.len() >= 2 {
            let key = args[0].as_string().unwrap_or("unknown".to_string());
            facts.set_value(&key, args[1].clone())?;
        }
        Ok(Value::Boolean(true))
    });

    engine.register_function("logMessage", |args, _| {
        println!("📝 {}", args[0]);
        Ok(Value::Boolean(true))
    });

    engine.register_function("sendNotification", |args, _| {
        println!("📧 Notification: {} → {}", args[0], args[1]);
        Ok(Value::Boolean(true))
    });

    // Set up test facts
    let facts = Facts::new();
    
    // Customer service scenario
    let mut customer_message = HashMap::new();
    customer_message.insert("type".to_string(), Value::String("complaint".to_string()));
    customer_message.insert("text".to_string(), Value::String("This service is terrible!".to_string()));
    facts.add_value("CustomerMessage", Value::Object(customer_message))?;

    // Transaction for fraud detection
    let mut transaction = HashMap::new();
    transaction.insert("amount".to_string(), Value::Number(2500.0));
    transaction.insert("userId".to_string(), Value::String("user123".to_string()));
    facts.add_value("Transaction", Value::Object(transaction))?;

    // Customer for tier prediction
    let mut customer = HashMap::new();
    customer.insert("id".to_string(), Value::String("VIP_customer_456".to_string()));
    customer.insert("tier".to_string(), Value::String("pending".to_string()));
    customer.insert("needsReview".to_string(), Value::Boolean(true));
    facts.add_value("Customer", Value::Object(customer))?;

    // Product for dynamic pricing
    let mut product = HashMap::new();
    product.insert("category".to_string(), Value::String("dynamic".to_string()));
    product.insert("basePrice".to_string(), Value::Number(150.0));
    product.insert("demand".to_string(), Value::Number(1.3));
    facts.add_value("Product", Value::Object(product))?;

    let mut ticket = HashMap::new();
    facts.add_value("Ticket", Value::Object(ticket))?;

    // Execute AI-powered rules
    println!("\n🚀 Executing AI-Powered Rule Engine...\n");
    let result = engine.execute(&facts)?;
    
    println!("\n📊 Execution Results:");
    println!("   Rules fired: {}", result.rules_fired);
    println!("   Cycles: {}", result.cycles);
    println!("   Duration: {:?}", result.duration);
    
    Ok(())
}

🔍 Dependency Analysis Example

use rust_rule_engine::dependency::DependencyAnalyzer;

fn analyze_rule_dependencies() -> Result<(), Box<dyn std::error::Error>> {
    let grl_content = r#"
        rule "VIPUpgrade" {
            when Customer.TotalSpent > 1000.0 && Customer.IsVIP == false
            then 
                Customer.setIsVIP(true);
                Customer.setTier("GOLD");
        }
        
        rule "VIPBenefits" {
            when Customer.IsVIP == true
            then
                Order.setDiscountRate(0.15);
                log("VIP discount applied");
        }
    "#;

    let analyzer = DependencyAnalyzer::new();
    let analysis = analyzer.analyze_grl_rules(grl_content)?;
    
    // Show detected dependencies
    for rule in &analysis.rules {
        println!("📋 Rule '{}' reads: {:?}", rule.name, rule.reads);
        println!("✏️  Rule '{}' writes: {:?}", rule.name, rule.writes);
    }
    
    // Check for conflicts
    let conflicts = analysis.find_conflicts();
    if conflicts.is_empty() {
        println!("✅ No conflicts detected - rules can execute safely in parallel");
    } else {
        println!("⚠️  {} conflicts detected", conflicts.len());
    }
    
    Ok(())
}

🎯 GRL Rule Language Features

Supported Syntax

// Basic rule
rule "RuleName" salience 10 {
    when
        Object.Property > 100 &&
        Object.Status == "ACTIVE"
    then
        Object.setCategory("HIGH_VALUE");
        processTransaction(Object.Id, Object.Amount);
        log("Rule executed successfully");
}

// Rule with no-loop protection (prevents infinite self-activation)
rule "ScoreUpdater" no-loop salience 15 {
    when
        Player.score < 100
    then
        set(Player.score, Player.score + 10);
        log("Score updated with no-loop protection");
}

Operators

• Comparison: >, >=, <, <=, ==, !=
• Logical: &&, ||
• Value Types: Numbers, Strings (quoted), Booleans (true/false)

Actions

• Method Calls: Object.method(args)
• Function Calls: functionName(args)
• Logging: log("message")

📚 Examples

🛒 E-commerce Rules

rule "VIPCustomer" salience 20 {
    when
        Customer.TotalSpent > 5000.0 && Customer.YearsActive >= 2
    then
        Customer.setTier("VIP");
        sendWelcomePackage(Customer.Email, "VIP");
        applyDiscount(Customer.Id, 15.0);
        log("Customer upgraded to VIP");
}

rule "LoyaltyReward" salience 15 {
    when
        Customer.OrderCount >= 50
    then
        addLoyaltyPoints(Customer.Id, 500);
        log("Loyalty reward applied");
}

🚗 Vehicle Monitoring

rule "SpeedLimit" salience 25 {
    when
        Vehicle.Speed > Vehicle.SpeedLimit
    then
        triggerAlert(Vehicle.Id, "SPEED_VIOLATION");
        logViolation(Vehicle.Driver, Vehicle.Speed);
        Vehicle.setStatus("FLAGGED");
}

rule "MaintenanceDue" salience 10 {
    when
        Vehicle.Mileage > Vehicle.NextMaintenance
    then
        scheduleService(Vehicle.Id, Vehicle.Mileage);
        notifyDriver(Vehicle.Driver, "Maintenance due");
}

🧩 Pattern Matching Examples

rule "VIPServiceActivation" "Activate VIP service when VIP customer exists" salience 20 {
    when
        exists(Customer.tier == "VIP")
    then
        System.vipServiceActive = true;
        log("VIP service activated - VIP customer detected");
}

rule "MarketingCampaign" "Send marketing when no pending orders" salience 15 {
    when
        !exists(Order.status == "pending")
    then
        Marketing.emailSent = true;
        sendMarketingEmail();
        log("Marketing campaign sent - no pending orders");
}

rule "ShippingEnable" "Enable shipping when all orders processed" salience 10 {
    when
        forall(Order.status == "processed")
    then
        Shipping.enabled = true;
        enableShippingService();
        log("Shipping enabled - all orders processed");
}

rule "ComplexBusinessLogic" "Complex pattern combination" salience 25 {
    when
        exists(Customer.tier == "VIP") && 
        !exists(Alert.priority == "high") &&
        forall(Order.status == "processed")
    then
        System.premiumModeEnabled = true;
        activatePremiumFeatures();
        log("Premium mode activated - all conditions met");
}

Run Pattern Matching Examples:

# Programmatic pattern matching demo
cargo run --example pattern_matching_demo

# GRL file-based pattern matching
cargo run --example simple_pattern_matching_grl

# Complex patterns from GRL files  
cargo run --example pattern_matching_from_grl

🌐 REST API with Monitoring

The engine provides a production-ready REST API with comprehensive analytics monitoring.

Quick Start

# Run the REST API server with full analytics monitoring
cargo run --example rest_api_monitoring

# Or use the demo script for testing
./demo_rest_api.sh

Available Endpoints

Rule Execution:

• POST /api/v1/rules/execute - Execute rules with provided facts
• POST /api/v1/rules/batch - Execute rules in batch mode

Analytics & Monitoring:

• GET /api/v1/analytics/dashboard - Comprehensive analytics dashboard
• GET /api/v1/analytics/stats - Overall performance statistics
• GET /api/v1/analytics/recent - Recent execution activity
• GET /api/v1/analytics/recommendations - Performance optimization recommendations
• GET /api/v1/analytics/rules/{rule_name} - Rule-specific analytics

System:

• GET / - API documentation
• GET /api/v1/health - Health check
• GET /api/v1/status - System status

Example Requests

Execute Rules:

curl -X POST "http://localhost:3000/api/v1/rules/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "facts": {
      "Customer": {
        "Age": 35,
        "IsNew": false,
        "OrderCount": 75,
        "TotalSpent": 15000.0,
        "YearsActive": 3,
        "Email": "customer@example.com"
      },
      "Order": {
        "Amount": 750.0,
        "CustomerEmail": "customer@example.com"
      }
    }
  }'

Analytics Dashboard:

curl "http://localhost:3000/api/v1/analytics/dashboard"

Sample Response:

{
  "overall_stats": {
    "total_executions": 1250,
    "avg_execution_time_ms": 2.3,
    "success_rate": 99.8,
    "rules_per_second": 435.2,
    "uptime_hours": 24.5
  },
  "top_performing_rules": [
    {
      "name": "VIPCustomerRule",
      "execution_count": 340,
      "avg_duration_ms": 1.8,
      "success_rate": 100.0
    }
  ],
  "recommendations": [
    "Consider caching customer data to improve performance",
    "Rule 'ComplexValidation' shows high execution time"
  ]
}

Production Configuration

The REST API includes:

• Real-time Analytics: Live performance monitoring
• Health Checks: Comprehensive system health monitoring
• CORS Support: Cross-origin resource sharing
• Error Handling: Proper HTTP status codes and error messages
• Sampling: Configurable analytics sampling for high-volume scenarios
• Memory Management: Automatic cleanup and retention policies

⚡ Performance & Architecture

Benchmarks

Performance benchmarks on a typical development machine:

Simple Rule Execution:
• Single condition rule:     ~4.5 µs per execution
• With custom function call: ~4.8 µs per execution

Complex Rule Execution:
• Multi-condition rules:     ~2.7 µs per execution  
• 3 rules with conditions:   ~2.8 µs per execution

Rule Parsing:
• Simple GRL rule:          ~1.1 µs per parse
• Medium complexity rule:   ~1.4 µs per parse  
• Complex multi-line rule:  ~2.0 µs per parse

Facts Operations:
• Create complex facts:     ~1.8 µs
• Get nested fact:          ~79 ns
• Set nested fact:          ~81 ns

Memory Usage:
• Base engine overhead:     ~10KB
• Per rule storage:         ~1-2KB  
• Per fact storage:         ~100-500 bytes

Run benchmarks: cargo bench

Key Performance Insights:

• Ultra-fast execution: Rules execute in microseconds
• Efficient parsing: GRL rules parse in under 2µs
• Optimized facts: Nanosecond-level fact operations
• Low memory footprint: Minimal overhead per rule
• Scales linearly: Performance consistent across rule counts

🏆 Performance Comparison

Benchmark comparison with other rule engines:

Language/Engine        Rule Execution    Memory Usage    Startup Time
─────────────────────────────────────────────────────────────────────
Rust (this engine)     2-5µs            1-2KB/rule     ~1ms
.NET Rules Engine       15-50µs          3-8KB/rule     ~50-100ms
Go Rules Framework      10-30µs          2-5KB/rule     ~10-20ms
Java Drools            50-200µs          5-15KB/rule    ~200-500ms
Python rule-engine     500-2000µs        8-20KB/rule    ~100-300ms

Rust Advantages:

• 10x faster than .NET rule engines
• 5x faster than Go-based rule frameworks
• 50x faster than Java Drools
• 400x faster than Python implementations
• Zero GC pauses (unlike .NET/Java/Go)
• Minimal memory footprint
• Instant startup time

Why Rust Wins:

• No garbage collection overhead
• Zero-cost abstractions
• Direct memory management
• LLVM optimizations
• No runtime reflection costs

Key Design Decisions

• GRL-Only: Removed JSON support for cleaner, focused API
• Dual Sources: Support both file-based and inline rule definitions
• Custom Functions: Extensible function registry for business logic
• Builder Pattern: Fluent API for easy engine configuration
• Type Safety: Leverages Rust's type system for runtime safety
• Zero-Copy: Efficient string and memory management

🔍 Advanced Dependency Analysis (v0.3.0+)

The rule engine features sophisticated AST-based dependency analysis that automatically detects field dependencies and potential conflicts between rules.

Smart Field Detection

use rust_rule_engine::{RuleEngineBuilder, dependency::DependencyAnalyzer};

// Automatic field dependency detection
let rules = r#"
    rule "DiscountRule" {
        when Customer.VIP == true && Order.Amount > 100.0
        then 
            Order.setDiscount(0.2);
            Customer.setPoints(Customer.Points + 50);
    }
    
    rule "ShippingRule" {
        when Order.Amount > 50.0
        then
            Order.setFreeShipping(true);
            log("Free shipping applied");
    }
"#;

let analyzer = DependencyAnalyzer::new();
let analysis = analyzer.analyze_grl_rules(rules)?;

// Automatically detected dependencies:
// DiscountRule reads: [Customer.VIP, Order.Amount, Customer.Points]
// DiscountRule writes: [Order.Discount, Customer.Points]
// ShippingRule reads: [Order.Amount]  
// ShippingRule writes: [Order.FreeShipping]

Conflict Detection

// Detect read-write conflicts between rules
let conflicts = analysis.find_conflicts();
for conflict in conflicts {
    println!("⚠️  Conflict: {} reads {} while {} writes {}",
        conflict.reader_rule, conflict.field,
        conflict.writer_rule, conflict.field
    );
}

// Smart execution ordering based on dependencies
let execution_order = analysis.suggest_execution_order();

Advanced Features

• 🎯 AST-Based Analysis: Proper parsing instead of regex pattern matching
• 🔄 Recursive Conditions: Handles nested condition groups (AND/OR/NOT)
• 🧠 Function Side-Effects: Infers field modifications from function calls
• ⚡ Zero False Positives: Accurate dependency detection
• 📊 Conflict Resolution: Automatic rule ordering suggestions
• 🚀 Parallel Safety: Enables safe concurrent rule execution

📋 API Reference

Core Types

// Main engine builder
RuleEngineBuilder::new()
    .with_rule_file("path/to/rules.grl")?
    .with_inline_grl("rule content")?
    .with_config(config)
    .build()

// Value types
Value::Integer(42)
Value::Number(3.14)
Value::String("text".to_string())
Value::Boolean(true)
Value::Object(HashMap<String, Value>)

// Facts management
let facts = Facts::new();
facts.add_value("Object", value)?;
facts.get("Object")?;

// Execution results
result.rules_fired       // Number of rules that executed
result.cycle_count       // Number of execution cycles
result.execution_time    // Duration of execution

Function Registration

engine.register_function("functionName", |args, facts| {
    // args: Vec<Value> - function arguments
    // facts: &Facts - current facts state
    // Return: Result<Value, RuleEngineError>
    
    let param1 = &args[0];
    let param2 = args[1].as_number().unwrap_or(0.0);
    
    // Your custom business logic here
    println!("Function called with: {:?}", args);
    
    Ok(Value::String("Success".to_string()))
});

⚡ Parallel Rule Execution

The engine supports parallel execution for improved performance with large rule sets:

use rust_rule_engine::engine::parallel::{ParallelEngine, ParallelConfig};

// Create parallel engine with custom configuration
let config = ParallelConfig {
    enabled: true,
    max_threads: 4,
};

let mut engine = ParallelEngine::new(config);

// Add rules and facts
engine.add_rule(rule);
engine.insert_fact("User", user_data);

// Execute rules in parallel
let result = engine.execute_parallel(10).await;
println!("Rules fired: {}", result.total_rules_fired);
println!("Execution time: {:?}", result.execution_time);
println!("Parallel speedup: {:.2}x", result.parallel_speedup);

Parallel Execution Examples

# Simple parallel demo
cargo run --example simple_parallel_demo

# Performance comparison
cargo run --example financial_stress_test

🌐 Distributed & Cloud Features

Scale your rule engine across multiple nodes for high-performance distributed processing:

Architecture Overview

                    ┌─────────────────────┐
                    │   Load Balancer     │
                    │   (Route Requests)  │
                    └──────────┬──────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
   ┌─────────┐            ┌─────────┐            ┌─────────┐
   │ Node 1  │            │ Node 2  │            │ Node 3  │
   │Validation│           │ Pricing │            │ Loyalty │
   │  Rules  │            │  Rules  │            │  Rules  │
   └─────────┘            └─────────┘            └─────────┘
        │                      │                      │
        └──────────────────────┼──────────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │   Shared Data       │
                    │ (Redis/PostgreSQL)  │
                    └─────────────────────┘

Performance Benefits

• ⚡ 3x Performance: Parallel processing across specialized nodes
• 🛡️ Fault Tolerance: If one node fails, others continue operation
• 📈 Horizontal Scaling: Add nodes to increase capacity
• 🌍 Geographic Distribution: Deploy closer to users for reduced latency

Quick Demo

# Compare single vs distributed processing
cargo run --example distributed_concept_demo

Results:

Single Node:    1.4 seconds (sequential)
Distributed:    0.47 seconds (parallel)
→ 3x Performance Improvement!

Implementation Guide

See our comprehensive guides:

• 📚 Distributed Architecture Guide
• 🚀 Real-world Examples
• 🔧 Implementation Roadmap

Cloud Deployment

Deploy on major cloud platforms:

Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rule-engine-workers
spec:
  replicas: 3
  selector:
    matchLabels:
      app: rule-engine

Docker:

FROM rust:alpine
COPY target/release/rust-rule-engine /app/
EXPOSE 8080
CMD ["/app/rust-rule-engine"]

When to Use Distributed Architecture

✅ Recommended for:

• High traffic (>10,000 requests/day)
• Complex rule sets (>500 rules)
• High availability requirements
• Geographic distribution needs

❌ Not needed for:

• Simple applications (<100 rules)
• Low traffic scenarios
• Development/prototyping
• Limited infrastructure budget

🧪 All Examples

Core Features

# Basic rule execution
cargo run --example grule_demo

# E-commerce rules
cargo run --example ecommerce

# Custom functions
cargo run --example custom_functions_demo

# Method calls
cargo run --example method_calls_demo

Workflow Engine (v0.8.0)

# Basic workflow demo with order processing
cargo run --example workflow_engine_demo

# Advanced workflow with scheduled tasks
cargo run --example advanced_workflow_demo

Action Handlers (v0.7.1)

# Action handlers with programmatic API
cargo run --example action_handlers_demo

# Action handlers from GRL files
cargo run --example action_handlers_grl_demo

Performance & Scaling

# Parallel processing comparison
cargo run --example simple_parallel_demo

# Financial stress testing
cargo run --example financial_stress_test

# Distributed architecture demo
cargo run --example distributed_concept_demo

Advanced Features

# Pattern matching (v0.7.0)
cargo run --example pattern_matching_demo
cargo run --example simple_pattern_matching_grl
cargo run --example pattern_matching_from_grl

# REST API with analytics
cargo run --example rest_api_monitoring

# Analytics and monitoring
cargo run --example analytics_demo

# Rule file processing
cargo run --example rule_file_functions_demo

# Advanced dependency analysis
cargo run --example advanced_dependency_demo

Production Examples

# Fraud detection system
cargo run --example fraud_detection

# Complete speedup demo
cargo run --example complete_speedup_demo

# Debug conditions
cargo run --example debug_conditions

🌊 Streaming Rule Engine (v0.2.0+)

For real-time event processing, enable the streaming feature:

## 🌊 Streaming Rule Engine (v0.2.0+)

For real-time rule processing with streaming data:

```rust
use rust_rule_engine::streaming::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut engine = StreamRuleEngine::new();
    
    // Add streaming rules
    engine.add_rule(r#"
    rule "HighVolumeAlert" {
        when
            WindowEventCount > 100 && volumeSum > 1000000
        then
            AlertService.trigger("High volume detected");
    }
    "#).await?;
    
    // Register action handlers
    engine.register_action_handler("AlertService", |action| {
        println!("🚨 Alert: {:?}", action.parameters);
    }).await;
    
    // Start processing
    engine.start().await?;
    
    // Send events
    let event = StreamEvent::new("TradeEvent", data, "exchange");
    engine.send_event(event).await?;
    
    Ok(())
}

Streaming Features:

• ⏰ Time Windows: Sliding/tumbling window aggregations
• 📊 Real-time Analytics: Count, sum, average, min/max over windows
• 🎯 Pattern Matching: Event correlation and filtering
• ⚡ High Throughput: Async processing with backpressure handling
• 🚨 Action Handlers: Custom callbacks for rule consequences

Real-World Integration Examples

🔌 Kafka Consumer

use rdkafka::consumer::{Consumer, StreamConsumer};

async fn consume_from_kafka(engine: Arc<StreamRuleEngine>) {
    let consumer: StreamConsumer = ClientConfig::new()
        .set("group.id", "trading-group")
        .set("bootstrap.servers", "localhost:9092")
        .create().unwrap();
    
    consumer.subscribe(&["trading-events"]).unwrap();
    
    loop {
        match consumer.recv().await {
            Ok(message) => {
                let event = parse_kafka_message(message);
                engine.send_event(event).await?;
            }
            Err(e) => eprintln!("Kafka error: {}", e),
        }
    }
}

🌐 WebSocket Stream

use tokio_tungstenite::{connect_async, tungstenite::Message};

async fn consume_from_websocket(engine: Arc<StreamRuleEngine>) {
    let (ws_stream, _) = connect_async("wss://api.exchange.com/stream").await?;
    let (_, mut read) = ws_stream.split();
    
    while let Some(msg) = read.next().await {
        match msg? {
            Message::Text(text) => {
                let trade_data: TradeData = serde_json::from_str(&text)?;
                let event = convert_to_stream_event(trade_data);
                engine.send_event(event).await?;
            }
            _ => {}
        }
    }
}

🔄 HTTP API Polling

async fn poll_trading_api(engine: Arc<StreamRuleEngine>) {
    let client = reqwest::Client::new();
    let mut interval = interval(Duration::from_secs(1));
    
    loop {
        interval.tick().await;
        
        match client.get("https://api.exchange.com/trades").send().await {
            Ok(response) => {
                let trades: Vec<Trade> = response.json().await?;
                
                for trade in trades {
                    let event = StreamEvent::new(
                        "TradeEvent",
                        trade.to_hashmap(),
                        "exchange_api"
                    );
                    engine.send_event(event).await?;
                }
            }
            Err(e) => eprintln!("API error: {}", e),
        }
    }
}

🗄️ Database Change Streams

async fn watch_database_changes(engine: Arc<StreamRuleEngine>) {
    let mut change_stream = db.collection("trades")
        .watch(None, None).await?;
    
    while let Some(change) = change_stream.next().await {
        let change_doc = change?;
        
        if let Some(full_document) = change_doc.full_document {
            let event = StreamEvent::new(
                "DatabaseChange",
                document_to_hashmap(full_document),
                "mongodb"
            );
            engine.send_event(event).await?;
        }
    }
}

📂 File Watching

use notify::{Watcher, RecursiveMode, watcher};

async fn watch_log_files(engine: Arc<StreamRuleEngine>) {
    let (tx, mut rx) = tokio::sync::mpsc::channel(100);
    
    let mut watcher = watcher(move |res| {
        // Parse log lines into StreamEvents
    }, Duration::from_secs(1))?;
    
    watcher.watch("/var/log/trading", RecursiveMode::Recursive)?;
    
    while let Some(file_event) = rx.recv().await {
        let stream_event = parse_log_event(file_event);
        engine.send_event(stream_event).await?;
    }
}

Use Case Examples

📈 Financial Trading

rule "CircuitBreaker" {
    when
        priceMax > 200.0 || priceMin < 50.0
    then
        MarketService.halt("extreme_movement");
}

🌡️ IoT Monitoring

rule "OverheatingAlert" {
    when
        temperatureAverage > 80.0 && WindowEventCount > 20
    then
        CoolingSystem.activate();
        AlertService.notify("overheating_detected");
}

🛡️ Fraud Detection

rule "SuspiciousActivity" {
    when
        transactionCountSum > 10 && amountAverage > 1000.0
    then
        SecurityService.flag("potential_fraud");
        AccountService.freeze();
}

📊 E-commerce Analytics

rule "FlashSaleOpportunity" {
    when
        viewCountSum > 1000 && conversionRateAverage < 0.02
    then
        PromotionService.trigger("flash_sale");
        InventoryService.prepare();
}

See docs/STREAMING.md for complete documentation and examples.

📊 Advanced Analytics & Performance Monitoring (v0.3.0+)

Get deep insights into your rule engine performance with built-in analytics and monitoring:

🔧 Quick Analytics Setup

use rust_rule_engine::{RustRuleEngine, AnalyticsConfig, RuleAnalytics};

// Configure analytics for production use
let analytics_config = AnalyticsConfig {
    track_execution_time: true,
    track_memory_usage: true,
    track_success_rate: true,
    sampling_rate: 0.8,  // 80% sampling for high-volume production
    retention_period: Duration::from_secs(30 * 24 * 60 * 60), // 30 days
    max_recent_samples: 100,
};

// Enable analytics
let analytics = RuleAnalytics::new(analytics_config);
engine.enable_analytics(analytics);

// Execute rules - analytics automatically collected
let result = engine.execute(&facts)?;

// Access comprehensive insights
if let Some(analytics) = engine.analytics() {
    let stats = analytics.overall_stats();
    println!("Total executions: {}", stats.total_evaluations);
    println!("Average execution time: {:.2}ms", 
        stats.avg_execution_time.as_secs_f64() * 1000.0);
    println!("Success rate: {:.1}%", stats.success_rate);
    
    // Get optimization recommendations
    let recommendations = analytics.generate_recommendations();
    for rec in recommendations {
        println!("💡 {}", rec);
    }
}

🔄 No-Loop Protection

Prevent rules from infinitely triggering themselves - essential for rules that modify their own conditions:

🎯 The Problem

// ❌ Without no-loop: INFINITE LOOP!
rule "ScoreBooster" {
    when
        Player.score < 100
    then
        set(Player.score, Player.score + 10);  // This changes the condition!
}
// Rule keeps firing: 50 → 60 → 70 → 80 → 90 → 100 → STOP (only due to max_cycles)

✅ The Solution

// ✅ With no-loop: SAFE!
rule "ScoreBooster" no-loop {
    when
        Player.score < 100
    then
        set(Player.score, Player.score + 10);  // Rule fires once per cycle
}
// Rule fires once: 50 → 60, then waits for next cycle

🧪 Usage Examples

use rust_rule_engine::*;

// Method 1: Via GRL parsing
let grl = r#"
    rule "SafeUpdater" no-loop salience 10 {
        when Player.level < 5
        then set(Player.level, Player.level + 1);
    }
"#;
let rules = GRLParser::parse_rules(grl)?;

// Method 2: Via API
let rule = Rule::new("SafeUpdater".to_string(), conditions, actions)
    .with_no_loop(true)
    .with_salience(10);

// Method 3: Multiple positions supported
// rule "Name" no-loop salience 10 { ... }  ✅
// rule "Name" salience 10 no-loop { ... }  ✅

🔬 How It Works

1. Per-Cycle Tracking: Engine tracks which rules fired in current cycle
2. Skip Logic: Rules with no_loop=true skip if already fired this cycle
3. Fresh Start: Tracking resets at beginning of each new cycle
4. Drools Compatible: Matches Drools behavior exactly

🎮 Real Example

fn demo_no_loop() -> Result<()> {
    let grl = r#"
        rule "LevelUp" no-loop {
            when Player.xp >= 100
            then 
                set(Player.level, Player.level + 1);
                set(Player.xp, 0);
                log("Player leveled up!");
        }
    "#;
    
    let rules = GRLParser::parse_rules(grl)?;
    // Rule fires once: level 1→2, xp 150→0
    // Without no-loop: would fire again since xp >= 100 still true initially
}

📈 Analytics Features

• ⏱️ Execution Timing: Microsecond-precision rule performance tracking
• 📊 Success Rate Monitoring: Track fired vs evaluated rule ratios
• 💾 Memory Usage Estimation: Optional memory footprint analysis
• 🎯 Performance Rankings: Identify fastest and slowest rules
• 🔮 Smart Recommendations: AI-powered optimization suggestions
• 📅 Timeline Analysis: Recent execution history and trends
• ⚙️ Production Sampling: Configurable sampling rates for high-volume environments
• 🗂️ Automatic Cleanup: Configurable data retention policies

🎛️ Production Configuration

// Production configuration with optimized settings
let production_config = AnalyticsConfig::production(); // Built-in production preset

// Or custom configuration
let custom_config = AnalyticsConfig {
    track_execution_time: true,
    track_memory_usage: false,    // Disable for performance
    track_success_rate: true,
    sampling_rate: 0.1,          // 10% sampling for high traffic
    retention_period: Duration::from_secs(7 * 24 * 60 * 60), // 1 week
    max_recent_samples: 50,      // Limit memory usage
};

📊 Rich Analytics Dashboard

// Get comprehensive performance report
let analytics = engine.analytics().unwrap();

// Overall statistics
let stats = analytics.overall_stats();
println!("📊 Performance Summary:");
println!("  Rules: {}", stats.total_rules);
println!("  Executions: {}", stats.total_evaluations);
println!("  Success Rate: {:.1}%", stats.success_rate);
println!("  Avg Time: {:.2}ms", stats.avg_execution_time.as_secs_f64() * 1000.0);

// Top performing rules
for rule_metrics in analytics.slowest_rules(3) {
    println!("⚠️ Slow Rule: {} ({:.2}ms avg)", 
        rule_metrics.rule_name, 
        rule_metrics.avg_execution_time().as_secs_f64() * 1000.0
    );
}

// Recent activity timeline
for event in analytics.get_recent_events(5) {
    let status = if event.success { "✅" } else { "❌" };
    println!("{} {} - {:.2}ms", status, event.rule_name, 
        event.duration.as_secs_f64() * 1000.0);
}

🔍 Performance Insights

The analytics system provides actionable insights:

• Slow Rule Detection: "Consider optimizing 'ComplexValidation' - average execution time is 15.3ms"
• Low Success Rate Alerts: "Rule 'RareCondition' has low success rate (12.5%) - review conditions"
• Dead Rule Detection: "Rule 'ObsoleteCheck' never fires despite 156 evaluations - review logic"
• Memory Usage Warnings: "Rule 'DataProcessor' uses significant memory - consider optimization"

📚 Analytics Examples

Check out the comprehensive analytics demo:

# Run the analytics demonstration
cargo run --example analytics_demo

# Output includes:
# - Configuration summary
# - Performance rankings  
# - Success rate analysis
# - Optimization recommendations
# - Recent execution timeline

Key Benefits:

• 🚀 Performance Optimization: Identify bottlenecks automatically
• 📈 Production Monitoring: Real-time insights in live environments
• 🔧 Development Debugging: Detailed execution analysis during development
• 📊 Trend Analysis: Historical performance tracking and regression detection
• ⚡ Zero-Overhead Option: Configurable sampling with minimal performance impact

📋 Changelog

v0.3.0 (October 2025) - AST-Based Dependency Analysis & Advanced Analytics

• 🔍 Revolutionary Dependency Analysis: Complete rewrite from hard-coded pattern matching to proper AST parsing
• 🎯 Smart Field Detection: Recursive condition tree traversal for accurate field dependency extraction
• 🧠 Function Side-Effect Analysis: Intelligent inference of field modifications from function calls
• ⚡ Zero False Positives: Elimination of brittle string-based detection methods
• 🚀 Parallel Processing Foundation: AST-based analysis enables safe concurrent rule execution
• 📊 Advanced Conflict Detection: Real data flow analysis for read-write conflict identification
• 🏗️ Production-Ready Safety: Robust dependency analysis for enterprise-grade rule management
• 📈 Advanced Analytics System: Comprehensive performance monitoring and optimization insights
  • Real-time execution metrics with microsecond precision
  • Success rate tracking and trend analysis
  • Memory usage estimation and optimization recommendations
  • Production-ready sampling and data retention policies
  • Automated performance optimization suggestions
  • Rich analytics dashboard with timeline analysis
• 🌐 REST API with Monitoring: Production-ready web API with full analytics integration
  • Comprehensive REST endpoints for rule execution
  • Real-time analytics dashboard with performance insights
  • Health monitoring and system status endpoints
  • CORS support and proper error handling
  • Sample requests and complete API documentation

v0.2.x - Core Features & Streaming

• 🌊 Stream Processing: Real-time event processing with time windows
• 📊 Rule Templates: Parameterized rule generation system
• 🔧 Method Calls: Enhanced object method call support
• 📄 File-Based Rules: External .grl file support
• ⚡ Performance Optimizations: Microsecond-level rule execution

📄 License

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

📞 Support

• 📚 Documentation: docs.rs/rust-rule-engine
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Built with ❤️ in Rust 🦀