🧠 Rust Logic Graph

A high-performance reasoning graph framework for Rust with GRL (Grule Rule Language) support. Build complex workflows with conditional execution, topological ordering, and async processing.

✨ Key Features

🔥 GRL Support - rust-rule-engine v0.14.0 with RETE-UL algorithm (2-24x faster)
🔄 Topological Execution - Automatic DAG-based node ordering
⚡ Async Runtime - Built on Tokio for high concurrency
⚡ Parallel Execution - Automatic parallel execution of independent nodes (v0.5.0)
💾 Caching Layer - High-performance result caching with TTL, eviction policies, and memory limits (v0.5.0)
🧠 Memory Optimization - Context pooling and allocation tracking (v0.7.0)
🛠️ CLI Developer Tools - Graph validation, dry-run, profiling, and visualization (v0.5.0)
🎨 Web Graph Editor - Next.js visual editor with drag-and-drop interface (v0.8.0)
📊 Multiple Node Types - RuleNode, DBNode, AINode
📝 JSON Configuration - Simple workflow definitions
🎯 98% Drools Compatible - Easy migration from Java
🌊 Streaming Processing - Stream-based execution with backpressure (v0.3.0)
🗄️ Database Integrations - PostgreSQL, MySQL, Redis, MongoDB (v0.2.0)
🤖 AI/LLM Integrations - OpenAI, Claude, Ollama (v0.2.0)

🚀 Quick Start

Installation

[dependencies]
rust-logic-graph = "0.8.0"

# With specific integrations
rust-logic-graph = { version = "0.8.0", features = ["postgres", "openai"] }

# With all integrations
rust-logic-graph = { version = "0.8.0", features = ["all-integrations"] }

Simple Example

use rust_logic_graph::{RuleEngine, GrlRule};

let grl = r#"
rule "Discount" {
    when
        cart_total > 100 && is_member == true
    then
        discount = 0.15;
}
"#;

let mut engine = RuleEngine::new();
engine.add_grl_rule(grl)?;

🏢 Real-World Case Study: Purchasing Flow System

See a complete production implementation in case_study/ - A full-featured purchasing automation system built with Rust Logic Graph.

📊 System Overview

Problem: Automate purchasing decisions for inventory replenishment across multiple products, warehouses, and suppliers.

Solution: Business rules in GRL decide when/how much to order. Orchestrator executes the workflows.

🎯 Two Architecture Implementations

1. Microservices (v4.0) - 7 services with gRPC

Orchestrator (port 8080) - Workflow coordination
OMS Service (port 50051) - Order management data
Inventory Service (port 50052) - Stock levels
Supplier Service (port 50053) - Supplier information
UOM Service (port 50054) - Unit conversions
Rule Engine (port 50055) - GRL business rules
PO Service (port 50056) - Purchase order management

2. Monolithic - Single HTTP service

Same business logic as microservices
Single process on port 8080
Shared GRL rules file
Direct function calls instead of gRPC

🔥 GRL Business Rules (15 Rules)

rule "CalculateShortage" salience 120 no-loop {
  when
    required_qty > 0
  then
    Log("Calculating shortage...");
    shortage = required_qty - available_qty;
    Log("Shortage calculated");
}

rule "OrderMOQWhenShortageIsLess" salience 110 no-loop {
  when
    shortage > 0 && shortage < moq && is_active == true
  then
    Log("Shortage less than MOQ, ordering MOQ");
    order_qty = moq;
}

See full rules: purchasing_rules.grl

Microservices Communication Flow

This case study uses a gRPC-based communication pattern between small services. The high-level flow:

The Orchestrator receives a purchasing request (HTTP/gRPC) and queries services (OMS, Inventory, Supplier, UOM) to build a context for rule evaluation.
The Orchestrator sends the context to the Rule Engine service (gRPC). The Rule Engine evaluates the shared GRL rules and returns decision flags rather than performing side-effects.
Decision flags include fields like: should_create_po, should_send_po, po_status, send_method, and computed values such as order_qty, shortage, total_amount.
Based on flags, the Orchestrator calls the PO Service to create a purchase order, and if should_send_po is true, it instructs the Supplier Service to send the PO using the selected send_method (email/API).

Typical proto message fields (summary):

EvaluateRequest: product_id, required_qty, available_qty, moq, unit_price, lead_time
EvaluateResponse: should_create_po, should_send_po, po_status, send_method, order_qty, total_amount

This separation keeps rules pure (no side-effects) and centralizes execution decisions in the Orchestrator.

┌─────────────────────────────────────────────────────────────────────┐
│                         CLIENT (HTTP REST)                          │
└────────────────────────────────┬────────────────────────────────────┘
         │ POST /purchasing/flow
         ▼
        ┌────────────────────────┐
        │  Orchestrator Service  │ (Port 8080 - HTTP)
        │  ┌──────────────────┐  │
        │  │ Workflow Manager │  │ • Fetches data from services
        │  │ Pure Executor    │  │ • Calls rule engine for decisions
        │  └──────────────────┘  │ • Executes based on flags
        └────────┬───────────────┘
           │ (gRPC calls - parallel)
  ┌────────────────────┼────────────────────┬───────────────┐
  │                    │                    │               │
  ▼                    ▼                    ▼               ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐   ┌──────────────┐
│ OMS Service  │    │   Inventory  │    │   Supplier   │   │ UOM Service  │
│   :50051     │    │   Service    │    │   Service    │   │   :50054     │
│              │    │    :50052    │    │    :50053    │   │              │
│ • History    │    │ • Levels     │    │ • Info       │   │ • Conversion │
│ • Demand     │    │ • Available  │    │ • Pricing    │   │ • Factors    │
└──────────────┘    └──────────────┘    └──────────────┘   └──────────────┘
           │
           │ gRPC with context data
           ▼
        ┌────────────────────────┐
        │ Rule Engine Service    │ (Port 50055 - gRPC)
        │  ┌──────────────────┐  │
        │  │ GRL Rule Engine  │  │ • Evaluates business rules
        │  │ Decision Maker   │  │ • Returns calculations + flags
        │  │ (Calculation     │  │ • NO execution/side effects
        │  │  Mode)           │  │
        │  └─────────┬────────┘  │
        │            │           │
        │     ┌──────▼────────┐  │
        │     │ GRL Rules     │  │
        │     │ (15 rules)    │  │
        │     └───────────────┘  │
        └────────────────────────┘
           │
           │ Returns: {
           │   should_create_po: true,
           │   should_send_po: true,
           │   order_qty: 245,
           │   total_amount: 3797.50,
           │   approval_status: "auto_approved"
           │ }
           ▼
        ┌────────────────────────┐
        │  Orchestrator reads    │
        │  flags & executes:     │
        └────────┬───────────────┘
           │
    ┌────────────┴─────────────┐
    │                          │
    ▼                          ▼
  ┌──────────────┐          ┌──────────────┐
  │ PO Service   │          │  (Future)    │
  │   :50056     │          │ Notification │
  │              │          │   Service    │
  │ • CreatePO   │          │              │
  │ • SendPO     │          │ • Alerts     │
  └──────────────┘          │ • Emails     │
          └──────────────┘

Web Graph Editor (NEW in v0.8.0)

🌐 Online Editor: https://logic-graph-editor.amalthea.cloud/

Try the visual graph editor online - no installation required! Create workflows, define rules, and visualize your logic graphs with drag-and-drop.

CLI Tools (v0.5.0)

# Build the CLI tool
cargo build --release --bin rlg

# Validate a graph
./target/release/rlg validate --file examples/sample_graph.json

# Visualize graph structure
./target/release/rlg visualize --file examples/sample_graph.json --details

# Profile performance
./target/release/rlg profile --file examples/sample_graph.json --iterations 100

# Dry-run without execution
./target/release/rlg dry-run --file examples/sample_graph.json --verbose

Full CLI Documentation →

Run Examples

# Basic workflow
cargo run --example simple_flow

# GRL rules
cargo run --example grl_rules

# Advanced integration
cargo run --example grl_graph_flow

📚 Documentation

Document	Description
🏢 Case Study: Purchasing Flow	Real production system with microservices & monolithic implementations
Graph Editor Guide	Visual web-based graph editor with Next.js (NEW in v0.8.0)
Memory Optimization Guide	Context pooling and allocation tracking (v0.7.0)
CLI Tool Guide	Developer tools for validation, profiling, and visualization (v0.5.0)
Cache Guide	Caching layer with TTL and eviction policies (v0.5.0)
Migration Guide	Upgrade guide to v0.14.0 with RETE-UL (v0.5.0)
Integrations Guide	Database & AI integrations (v0.2.0)
GRL Guide	Complete GRL syntax and examples
Use Cases	33+ real-world applications
Extending	Create custom nodes and integrations
Implementation	Technical details

🎯 Use Cases

Rust Logic Graph powers applications in:

💰 Finance - Loan approval, fraud detection, risk assessment
🛒 E-commerce - Dynamic pricing, recommendations, fulfillment
🏥 Healthcare - Patient triage, clinical decisions, monitoring
🏭 Manufacturing - Predictive maintenance, QC automation
🛡️ Insurance - Claims processing, underwriting
📊 Marketing - Lead scoring, campaign optimization
⚖️ Compliance - AML monitoring, GDPR automation

View all 33+ use cases →

🏗️ Architecture

Rust Logic Graph architecture diagram

🔥 GRL Example

rule "HighValueLoan" salience 100 {
    when
        loan_amount > 100000 &&
        credit_score < 750
    then
        requires_manual_review = true;
        approval_tier = "senior";
}

rule "AutoApproval" salience 50 {
    when
        credit_score >= 700 &&
        income >= loan_amount * 3 &&
        debt_ratio < 0.4
    then
        auto_approve = true;
        interest_rate = 3.5;
}

Learn more about GRL →

📊 Performance

RETE-UL Algorithm: Advanced pattern matching with unlinking (v0.14.0)
2-24x Faster: Than v0.10 at 50+ rules
98% Drools Compatible: Easy migration path
Async by Default: High concurrency support
Parallel Execution: Automatic layer-based parallelism
Smart Caching: Result caching with TTL and eviction policies

🧪 Testing & CLI Tools

# Run all tests
cargo test

# Build CLI tool
cargo build --release --bin rlg

# Validate graph
./target/release/rlg validate --file examples/sample_graph.json

# Visualize graph structure
./target/release/rlg visualize --file examples/sample_graph.json

# Profile performance
./target/release/rlg profile --file examples/sample_graph.json --iterations 100

# Dry-run execution
./target/release/rlg dry-run --file examples/sample_graph.json --verbose

Test Results: ✅ 32/32 tests passing

Learn more about CLI tools →

📦 Project Status

Version: 0.8.0 (Latest) Status: Production-ready with web graph editor and real-world case study

What's Working

✅ Core graph execution engine
✅ RETE-UL algorithm (v0.14.0) - 2-24x faster
✅ Three node types (Rule, DB, AI)
✅ Topological sorting
✅ Async execution
✅ JSON I/O
✅ Database integrations (PostgreSQL, MySQL, Redis, MongoDB)
✅ AI integrations (OpenAI, Claude, Ollama)
✅ Streaming processing with backpressure and chunking
✅ Parallel execution with automatic layer detection
✅ Caching layer with TTL, eviction policies, memory limits (v0.5.0)
✅ Memory optimization with context pooling (v0.7.0)
✅ CLI Developer Tools - validate, profile, visualize, dry-run (v0.5.0)
✅ Web Graph Editor - Next.js visual editor with drag-and-drop (v0.8.0)
✅ Production Case Study - Purchasing flow with microservices & monolithic (v0.8.0)
✅ Stream operators (map, filter, fold)
✅ Comprehensive documentation

Roadmap

Streaming processing (v0.3.0) - COMPLETED ✅
Parallel node execution (v0.4.0) - COMPLETED ✅
Caching layer (v0.5.0) - COMPLETED ✅
CLI Developer Tools (v0.5.0) - COMPLETED ✅
RETE-UL upgrade (v0.5.0) - COMPLETED ✅
Memory Optimization (v0.7.0) - COMPLETED ✅
Web Graph Editor (v0.8.0) - COMPLETED ✅
Production Case Study (v0.8.0) - COMPLETED ✅
GraphQL API (v0.9.0)
Production release (v1.0.0)

See ROADMAP.md for details

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create your feature branch
Write tests for new features
Submit a pull request

📖 Examples

Example	Description	Lines
`simple_flow.rs`	Basic 3-node pipeline	36
`advanced_flow.rs`	Complex 6-node workflow	120
`grl_rules.rs`	GRL rule examples	110
`grl_graph_flow.rs`	GRL + Graph integration	140
`postgres_flow.rs`	PostgreSQL integration	100
`openai_flow.rs`	OpenAI GPT integration	150
`streaming_flow.rs`	Streaming with backpressure	200
`parallel_execution.rs`	Parallel node execution	250

CLI Tool Examples (v0.5.0)

File	Description
`examples/sample_graph.json`	Linear workflow with 5 nodes
`examples/cyclic_graph.json`	Graph with cycle for testing
`examples/sample_context.json`	Sample input data

See CLI_TOOL.md for usage examples

🌟 Why Rust Logic Graph?

vs. Traditional Rule Engines

✅ Async by default - No blocking I/O
✅ Type safety - Rust's type system
✅ Modern syntax - GRL support
✅ Graph-based - Complex workflows

vs. Workflow Engines

✅ Embedded - No external services
✅ Fast - Compiled Rust code
✅ Flexible - Custom nodes
✅ Rule-based - Business logic in rules

📝 Changelog

v0.8.0 (2025-11-20) - Web Editor & Production Case Study Release

New Features:

🎨 Web Graph Editor - Next.js visual editor with drag-and-drop
- Online version: https://logic-graph-editor.amalthea.cloud/
- React Flow-based graph visualization
- Real-time node editing and validation
- Export/import JSON workflows
- See Graph Editor Guide
🏢 Production Case Study - Complete purchasing flow system
- Microservices architecture (7 services with gRPC)
- Monolithic architecture (single HTTP service)
- 15 GRL business rules for purchasing decisions
- Kubernetes deployment manifests
- Docker Compose for local development
- Shared GRL rules proving portability
- See Case Study Documentation

Improvements:

Updated README with case study section
Added online graph editor link
Comprehensive production examples

Compatibility:

All tests passing
API backward compatible

v0.5.0 (2025-11-06) - Performance & Developer Tools Release

Breaking Changes:

⚡ Upgraded rust-rule-engine from v0.10 → v0.14.0
- Now uses RETE-UL algorithm (2-24x faster)
- Better memory efficiency
- Improved conflict resolution
- See Migration Guide

New Features:

🛠️ CLI Developer Tools (rlg binary)
- Graph validation with comprehensive checks
- Dry-run execution mode
- Performance profiling with statistics
- ASCII graph visualization
- See CLI Tool Guide
💾 Caching Layer - High-performance result caching
- TTL-based expiration
- Multiple eviction policies (LRU, LFU, FIFO)
- Memory limits and statistics
- See Cache Guide
⚡ Parallel Node Execution - Automatic detection and parallel execution
- Layer detection algorithm using topological sort
- Concurrent execution within layers
- Parallelism analysis and statistics
📊 ParallelExecutor - New executor with parallel capabilities
📝 New Examples - CLI examples and test graphs
✅ 32 Tests - Comprehensive test coverage

Improvements:

Updated documentation with CLI tools, caching, and migration guides
Performance benchmarking utilities
Example graph files for testing

Compatibility:

All 32 tests passing
API is backward compatible (100%)
Performance: 2-24x faster rule matching

v0.3.0 (2025-11-03) - Streaming & Performance Release

New Features:

🌊 Streaming Processing - Stream-based node execution
- Backpressure handling with bounded channels
- Large dataset support with chunking
- Stream operators (map, filter, fold, async map)
📝 New Example - streaming_flow.rs with 6 demonstrations
✅ 8 New Tests - Streaming module testing

Performance:

Processed 10,000 items in chunks
~432 items/sec throughput with backpressure

v0.2.0 (2025-11-02) - Integrations Release

New Features:

🗄️ Database Integrations - PostgreSQL, MySQL, Redis, MongoDB
🤖 AI/LLM Integrations - OpenAI GPT-4, Claude 3.5, Ollama
📝 Integration Examples - postgres_flow.rs, openai_flow.rs
📚 INTEGRATIONS.md - Comprehensive integration guide
🎛️ Feature Flags - Optional dependencies for integrations

v0.1.0 (2025-11-01) - Initial Release

Core Features:

🧠 Core graph execution engine
🔥 GRL (Grule Rule Language) integration
🔄 Topological sorting
⚡ Async execution with Tokio
📊 Three node types (Rule, DB, AI)
📝 JSON I/O for graphs
📚 4 working examples
✅ 6/6 tests passing

📄 License

MIT License - see LICENSE for details.

🔗 Links

Repository: https://github.com/KSD-CO/rust-logic-graph
rust-rule-engine: https://crates.io/crates/rust-rule-engine
Documentation: docs/
Issues: GitHub Issues

👥 Authors

James Vu - Initial work

🙏 Acknowledgments

Built with:

rust-rule-engine v0.14.0 - GRL support with RETE-UL
Tokio - Async runtime
Petgraph - Graph algorithms
Serde - Serialization
Clap - CLI framework

⭐ Star us on GitHub if you find this useful! ⭐

Documentation • Examples • Use Cases

rust-logic-graph 0.8.0

🧠 Rust Logic Graph

✨ Key Features

🚀 Quick Start

Installation

Simple Example

🏢 Real-World Case Study: Purchasing Flow System

📊 System Overview

🎯 Two Architecture Implementations

🔥 GRL Business Rules (15 Rules)

Microservices Communication Flow

Web Graph Editor (NEW in v0.8.0)

CLI Tools (v0.5.0)

Run Examples

📚 Documentation

🎯 Use Cases

🏗️ Architecture

🔥 GRL Example

📊 Performance

🧪 Testing & CLI Tools

📦 Project Status

What's Working

Roadmap

🤝 Contributing

📖 Examples

CLI Tool Examples (v0.5.0)

🌟 Why Rust Logic Graph?

vs. Traditional Rule Engines

vs. Workflow Engines

📝 Changelog

v0.8.0 (2025-11-20) - Web Editor & Production Case Study Release

v0.5.0 (2025-11-06) - Performance & Developer Tools Release

v0.3.0 (2025-11-03) - Streaming & Performance Release

v0.2.0 (2025-11-02) - Integrations Release

v0.1.0 (2025-11-01) - Initial Release

📄 License

🔗 Links

👥 Authors

🙏 Acknowledgments