# Rust Rule Engine v0.9.0 ๐ฆโก
[](https://crates.io/crates/rust-rule-engine)
[](https://docs.rs/rust-rule-engine)
[](https://opensource.org/licenses/MIT)
[](https://github.com/KSD-CO/rust-rule-engine/actions)
[](https://github.com/KSD-CO/rust-rule-engine)
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.
## ๏ฟฝ Table of Contents
- [๐ Key Features](#-key-features)
- [๐ฆ Installation](#-installation)
- [๐ฏ Quick Start](#-quick-start)
- [Basic Rule Engine with Built-in Plugins](#basic-rule-engine-with-built-in-plugins)
- [Simple Rule without Plugins](#simple-rule-without-plugins)
- [๐ Plugin System](#-plugin-system)
- [Built-in Plugins Overview](#built-in-plugins-overview)
- [Creating Custom Plugins](#creating-custom-plugins)
- [๐ฏ Advanced Features](#-advanced-features)
- [Knowledge Base Management](#knowledge-base-management)
- [Complex Data Objects](#complex-data-objects)
- [Method Calls and Functions](#method-calls-and-functions)
- [Error Handling and Debugging](#error-handling-and-debugging)
- [๐ Examples](#-examples)
- [๐ง Configuration](#-configuration)
- [Engine Configuration](#engine-configuration)
- [Plugin Configuration](#plugin-configuration)
- [๐ Performance](#-performance)
- [๐บ Roadmap](#-roadmap)
- [๐งฉ Advanced Pattern Matching](#-advanced-pattern-matching-v070)
- [๐ฏ Rule Attributes](#-rule-attributes-v060)
- [๐จ Advanced Action Handlers](#-advanced-action-handlers-v071)
- [๐ Advanced Workflow Engine](#-advanced-workflow-engine-v080-latest)
- [๐ค AI Integration](#-ai-integration-new)
- [๐จ Visual Rule Builder](#-visual-rule-builder-new)
- [๐ REST API with Monitoring](#-rest-api-with-monitoring)
- [โก Performance & Architecture](#-performance--architecture)
- [๐ Changelog](#-changelog)
- [๐ฏ GRL Rule Language Features](#-grl-rule-language-features)
- [๐ Distributed & Cloud Features](#-distributed--cloud-features)
- [๐ API Reference](#-api-reference)
- [๐ค Contributing](#-contributing)
- [๐ License](#-license)
- [๐ Acknowledgments](#-acknowledgments)
- [๐ Support](#-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`:
```toml
[dependencies]
rust-rule-engine = "0.9.0"
```
## ๐ฏ Quick Start
### Basic Rule Engine with Built-in Plugins
```rust
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
```rust
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
```rust
// 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
```rust
// 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
```rust
// 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
```rust
// 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
```rust
// 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
```rust
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
```rust
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
```rust
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
```rust
// 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
```rust
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:
```bash
cargo run --example builtin_plugins_demo
cargo run --example ecommerce
cargo run --example fraud_detection
```
## ๐ง Configuration
### Engine Configuration
```rust
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
```rust
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](CONTRIBUTING.md) for guidelines.
### Development Setup
```bash
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
```bash
# 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](LICENSE) file for details.
## ๐ Acknowledgments
- Inspired by [Grule](https://github.com/hyperjumptech/grule-rule-engine) rule engine
- Built with Rust's powerful type system and performance capabilities
- Community feedback and contributions
## ๐ Support
- ๐ [Documentation](https://docs.rs/rust-rule-engine)
- ๐ [Issue Tracker](https://github.com/KSD-CO/rust-rule-engine/issues)
- ๐ฌ [Discussions](https://github.com/KSD-CO/rust-rule-engine/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
```rust
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
```rust
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
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
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:
```rust
// 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
```grl
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](examples/action_handlers_demo.rs) - 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:
```rust
// Programmatic API
let condition = ConditionGroup::exists(
ConditionGroup::Single(Condition::new(
"Customer.tier".to_string(),
Operator::Equal,
Value::String("VIP".to_string()),
))
);
```
```grl
// 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:
```rust
// Programmatic API
let condition = ConditionGroup::not(
ConditionGroup::exists(
ConditionGroup::Single(Condition::new(
"Order.status".to_string(),
Operator::Equal,
Value::String("pending".to_string()),
))
)
);
```
```grl
// 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:
```rust
// Programmatic API
let condition = ConditionGroup::forall(
ConditionGroup::Single(Condition::new(
"Order.status".to_string(),
Operator::Equal,
Value::String("processed".to_string()),
))
);
```
```grl
// 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:
```grl
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](examples/pattern_matching_demo.rs) - Programmatic API
- [GRL Pattern Matching Demo](examples/simple_pattern_matching_grl.rs) - GRL file syntax
- [Complex Patterns from File](examples/pattern_matching_from_grl.rs) - 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:
```grl
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");
}
```
```rust
// 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:
```grl
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:
```grl
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:
```grl
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:
```grl
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:
```rust
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
```grl
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
```rust
// Register AI-powered functions
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`:
```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`:
```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");
}
```
```rust
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:
```rust
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:
```rust
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](https://visual-rule-builder.amalthea.cloud/)** - 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/](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
```grl
// 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:
```rust
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
```rust
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
```grl
// 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
```grl
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
```grl
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
```grl
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:**
```bash
# 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
```bash
# 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:**
```bash
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:**
```bash
curl "http://localhost:3000/api/v1/analytics/dashboard"
```
**Sample Response:**
```json
{
"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:
```text
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:
```text
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
```rust
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
```rust
// 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
```rust
// 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
```rust
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:
```rust
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
```bash
# 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
```bash
# 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](docs/distributed_features_guide.md)
- ๐ [Real-world Examples](docs/distributed_explained.md)
- ๐ง [Implementation Roadmap](docs/distributed_architecture.md)
### Cloud Deployment
Deploy on major cloud platforms:
**Kubernetes:**
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: rule-engine-workers
spec:
replicas: 3
selector:
matchLabels:
app: rule-engine
```
**Docker:**
```dockerfile
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
```bash
# 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)
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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**
```rust
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**
```rust
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**
```rust
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**
```rust
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**
```rust
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**
```rust
rule "CircuitBreaker" {
when
priceMax > 200.0 || priceMin < 50.0
then
MarketService.halt("extreme_movement");
}
```
#### ๐ก๏ธ **IoT Monitoring**
```rust
rule "OverheatingAlert" {
when
temperatureAverage > 80.0 && WindowEventCount > 20
then
CoolingSystem.activate();
AlertService.notify("overheating_detected");
}
```
#### ๐ก๏ธ **Fraud Detection**
```rust
rule "SuspiciousActivity" {
when
transactionCountSum > 10 && amountAverage > 1000.0
then
SecurityService.flag("potential_fraud");
AccountService.freeze();
}
```
#### ๐ **E-commerce Analytics**
```rust
rule "FlashSaleOpportunity" {
when
viewCountSum > 1000 && conversionRateAverage < 0.02
then
PromotionService.trigger("flash_sale");
InventoryService.prepare();
}
```
See [docs/STREAMING.md](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
```rust
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
```grl
// โ 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
```grl
// โ
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
```rust
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
```rust
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
```rust
// 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
```rust
// 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:
```bash
# 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](LICENSE) file for details.
## ๐ Support
- ๐ **Documentation**: [docs.rs/rust-rule-engine](https://docs.rs/rust-rule-engine)
- ๐ **Issues**: [GitHub Issues](https://github.com/KSD-CO/rust-rule-engine/issues)
- ๐ฌ **Discussions**: [GitHub Discussions](https://github.com/KSD-CO/rust-rule-engine/discussions)
---
**Built with โค๏ธ in Rust** ๐ฆ