fast-decision

A high-performance rule engine written in Rust with Python bindings, designed for applications that need to evaluate complex business rules with minimal latency and maximum throughput.

Features

• High Performance: Rust-powered engine with zero-cost abstractions
• Priority-based Execution: Rules sorted by priority (lower number = higher priority)
• Stop-on-First: Per-category flag to stop after first match
• MongoDB-style Operators: Familiar syntax with $eq, $ne, $gt, $lt, $gte, $lte, $and, $or
• Complex Logic: Support for nested AND/OR predicates
• Python Bindings: Native performance with idiomatic Python API via PyO3
• Memory Efficient: Minimal allocations in hot path, optimized data structures
• Benchmarked: Built-in performance benchmarks with Criterion

Use Cases

• Business rule engines
• Dynamic pricing systems
• Feature flags and A/B testing
• Access control and authorization
• Data validation and filtering
• Workflow automation

Installation

Rust

Add to your Cargo.toml:

[dependencies]
fast-decision = "0.1"

Python

pip install fast-decision

Or install from source:

git clone https://github.com/almayce/fast-decision.git
cd fast-decision
maturin develop --release

Quick Start

Rust Example

use fast_decision::{RuleEngine, RuleSet};
use serde_json::json;

fn main() {
    let rules_json = r#"
    {
      "categories": {
        "Pricing": {
          "stop_on_first": true,
          "rules": [
            {
              "id": "Platinum_Discount",
              "priority": 1,
              "conditions": {"user.tier": {"$eq": "Platinum"}},
              "action": "apply_20_percent_discount"
            },
            {
              "id": "Gold_Discount",
              "priority": 10,
              "conditions": {"user.tier": {"$eq": "Gold"}},
              "action": "apply_10_percent_discount"
            }
          ]
        }
      }
    }
    "#;

    let ruleset: RuleSet = serde_json::from_str(rules_json).unwrap();
    let engine = RuleEngine::new(ruleset);

    let data = json!({
        "user": {"tier": "Gold", "id": 123},
        "transaction": {"amount": 100}
    });

    let results = engine.execute(&data, &["Pricing"]);
    println!("Triggered rules: {:?}", results);
    // Output: ["Gold_Discount"]
}

Python Example

See python/README.md for detailed Python documentation.

from fast_decision import FastDecision

# Load rules from JSON file
engine = FastDecision("rules.json")

# Execute rules
data = {
    "user": {"tier": "Gold", "id": 123},
    "transaction": {"amount": 100}
}

results = engine.execute(data, categories=["Pricing"])
print(f"Triggered rules: {results}")
# Output: ['Gold_Discount']

Rule Format

Rules are defined in JSON with MongoDB-style syntax:

{
  "categories": {
    "CategoryName": {
      "stop_on_first": true,
      "rules": [
        {
          "id": "rule_identifier",
          "priority": 1,
          "conditions": {
            "field.path": {"$eq": "value"}
          },
          "action": "action_name"
        }
      ]
    }
  }
}

Supported Operators

Logical Operators

Implicit AND - Multiple conditions in one object:

{
  "conditions": {
    "age": {"$gte": 18, "$lt": 65},
    "status": {"$eq": "active"}
  }
}

Explicit OR - Use $or:

{
  "conditions": {
    "$or": [
      {"tier": {"$eq": "Platinum"}},
      {"score": {"$gt": 1000}}
    ]
  }
}

Nested Logic:

{
  "conditions": {
    "$or": [
      {"tier": {"$eq": "Platinum"}},
      {
        "tier": {"$eq": "Gold"},
        "amount": {"$gt": 500}
      }
    ]
  }
}

Performance

Benchmarks

Run benchmarks:

cargo bench

Optimization Features

• Rust backend: Native machine code performance
• Zero allocations in hot execution path
• Inline functions: Critical comparison functions marked #[inline(always)]
• Optimized data structures: Box<[String]> for path tokens, #[repr(u8)] for operators
• Pre-sorted rules: Rules sorted by priority at load time
• Direct conversion: Python dict → Rust without intermediate JSON serialization
• Link Time Optimization (LTO): Enabled in release profile

Performance Characteristics

• Rule evaluation: O(n) where n = number of rules in requested categories
• Field lookup: O(d) where d = depth of nested field path
• Memory: Minimal allocations during execution (only for results)

Development

# Run tests
cargo test

# Run Rust examples
cargo run --example demo

# Run benchmarks
cargo bench

# Build documentation
cargo doc --no-deps --open

# Run Python tests
cd python/tests
python test_features.py

# Run Python examples
cd python/examples
python example.py

Contributing

See CONTRIBUTING.md for development guidelines.

Architecture

fast-decision/
├── src/              # Rust core engine
│   ├── lib.rs        # Python bindings (PyO3)
│   ├── engine.rs     # Rule execution engine
│   └── types.rs      # Data structures
├── benches/          # Performance benchmarks
├── examples/         # Rust examples
├── python/           # Python bindings and examples
│   ├── examples/     # Usage examples
│   └── tests/        # Tests
├── Cargo.toml        # Rust configuration
└── pyproject.toml    # Python packaging

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.