# fast-decision
[](https://crates.io/crates/fast-decision)
[](https://pypi.org/project/fast-decision/)
[](https://github.com/almayce/fast-decision#license)
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 Evaluation**: Rules sorted by priority (lower number = higher priority)
- **Stop-on-First**: Per-category flag to stop after first match
- **Condition Operators**: Familiar syntax with `$equals`, `$not-equals`, `$greater-than`, `$less-than`, `$greater-than-or-equals`, `$less-than-or-equals`, `$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
Fast Decision is ideally suited for systems where performance and low decision latency are critical.
### 1. Core Business Logic and Processes
* **Business Rule Engines** (Classical rule systems for decision automation)
* Transaction Approval/Rejection (Fast checking of conditions for immediate decisions, e.g., limits or stop-lists).
* Commission and Fee Calculation (Determining the exact amount based on customer type, region, and transaction volume).
* Management of Complex Contract Conditions (Automating the verification of product or service compliance with contract terms).
* **Workflow Automation**
* Document Routing (Directing a request for approval to the correct department based on amount, document type, or initiator's role).
* Task Status Management (Automatic transition of a task to "Awaiting Review" status upon fulfillment of all preceding conditions).
### 2. Financial and Commercial
* **Dynamic Pricing Systems**
* Real-time Discount Calculation (Applying complex discount rules based on purchase history, loyalty level, inventory, and current promotions).
* Product Pricing Tier Determination (Instant assignment of a category based on product characteristics, critical for high-volume E-commerce).
* **Credit Scoring and Underwriting** (Fast risk assessment)
* Initial Application Scoring (Immediate filtering of applications that do not meet minimum criteria, using "Stop-on-First" logic for high performance).
* Fraud Detection (Rapid assessment of transaction patterns in real-time before processing).
### 3. Security and Authorization
* **Access Control and Authorization (ABAC)** (Access management based on roles and attributes)
* User Rights Determination (Granting access to a resource based not only on role but also on attributes: time of day, IP address, subscription level).
* API Request Control (Quick verification of every incoming request against allowed limits and conditions).
* **Feature Flags and A/B Testing**
* Feature Toggling (Determining which version of a feature a specific user should be shown, based on their ID, geography, or registration date).
* Traffic Splitting (Directing 10% of traffic to a new, experimental version of a service).
### 4. Data and Infrastructure
* **Data Validation and Filtering**
* Input Data Cleansing (Fast checking and discarding of incomplete or incorrect records before saving them to the database).
* Event Routing (Directing events from a general stream like Kafka/RabbitMQ to a specific handler based on event type or criticality).
* **Configuration and Settings** (Decision making for system configuration)
* System Configuration Determination (Selecting optimal service startup parameters based on environment, load, or other input data).
* Alerting and Monitoring (Triggering alerts only when a combination of multiple conditions is met: high CPU load **AND** low disk space).
### 5. Development and Code Governance
* **Priority-based Execution**
* Cascading Rule Application (For example, first applying a "Global Ban," then a "Special Permission," using numerical priorities).
* Stop on First Match (Using the "Stop-on-First" flag to boost performance in categories where one successful rule is sufficient).
* **Python Bindings** (Using the Rust engine within the Python ecosystem)
* Integration with Django/Flask (Using a high-performance Rule Engine for critical logic in standard Python applications).
* Fast Processing in Data Science (Applying rules to large data dictionaries for quick labeling or filtering before feeding into an ML model).
### 6. Telecommunications and IoT (Telecom & Internet of Things)
* **Real-time Data Processing** (Processing data in real-time with low latency)
* Sensor Data Filtering (Rapidly discarding noise or incorrect readings from IoT sensors directly at the edge network).
* Network Traffic Routing (Making decisions on packet direction based on IP addresses, ports, or protocols with minimal delay).
* **Edge Computing Decisions** (Decision making at the network edge)
* Autonomous Device Actions (Local decision making by an IoT device (e.g., turn a pump on/off) without relying on the central cloud, based on local rules).
### 7. Gaming Industry
* **Anti-Cheat Logic**
* Instant Verification of Suspicious Actions (Applying complex logic to detect unnatural player action patterns in real-time).
* **In-Game Events and Rewards**
* Reward Triggers (Automatic crediting of bonuses or initiation of events upon the fulfillment of a combination of in-game conditions).
### 8. Government Sector and Compliance
* **Regulatory Compliance Checks**
* Automatic Form Verification (Quickly determining if an application meets all governmental or internal regulatory requirements before submission).
* **Eligibility Determination**
* Criteria Calculation (Instantly determining whether a citizen is entitled to a specific service or benefit based on input data).
### 9. ML Optimization
* **Pre-Processing Filters**
* Low-Quality Data Exclusion (Quickly discarding records that may introduce noise into the model before they enter the training pipeline, saving computational resources).
* Basic Segmentation (Using rules to separate the incoming data stream by type before feeding them into specialized models).
* **Model Switching and Orchestration**
* Model Version Switching (Deciding which version of an ML model to use—old stable or new experimental—based on input parameters, such as region or risk level).
### 10. Content Management Systems (CMS)
* **Content Personalization**
* Dynamic Page Layout (Determining which ad banner, article, or product should be shown to a user based on their session, device, and browsing history).
* Automatic Moderation (Rapid verification of user-generated content—comments, listings—for compliance with stop-words, publishing frequency, or other rules, prior to manual review).
### 11. System Integration and Migration
* **Data Mapping and Transformation**
* Format Conversion (Using rules to transform a complex JSON event from a legacy system into the format required by a new system, for example, changing field names or merging values).
* **Legacy System Decoupling**
* "Shadow" Logic Execution (Running new rules parallel to legacy logic to compare results and ensure a smooth transition without downtime).
## Installation
### Rust
Add to your `Cargo.toml`:
```toml
[dependencies]
fast-decision = "0.2.4"
```
### Python
```bash
pip install fast-decision
```
Or install from source:
```bash
git clone https://github.com/almayce/fast-decision.git
cd fast-decision
maturin develop --release
```
## Quick Start
### Rust Example
```rust
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": {"$equals": "Platinum"}},
"action": "apply_20_percent_discount"
},
{
"id": "Gold_Discount",
"priority": 10,
"conditions": {"user.tier": {"$equals": "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.evaluate_rules(&data, &["Pricing"]);
println!("Triggered rules: {:?}", results);
// Output: ["Gold_Discount"]
}
```
### Python Example
See [python/README.md](python/README.md) for detailed Python documentation.
```python
from fast_decision import FastDecision
# Load rules from JSON file
engine = FastDecision("rules.json")
# Evaluate rules
data = {
"user": {"tier": "Gold", "id": 123},
"transaction": {"amount": 100}
}
results = engine.evaluate_rules(data, categories=["Pricing"])
print(f"Triggered rules: {results}")
# Output: ['Gold_Discount']
```
## Rule Format
Rules are defined in JSON:
```json
{
"categories": {
"CategoryName": {
"stop_on_first": true,
"rules": [
{
"id": "rule_identifier",
"priority": 1,
"conditions": {
"field.path": {"$equals": "value"}
},
"action": "action_name",
"metadata": {
"source": "Pricing Rules v2.3",
"tags": ["discount", "promotion"],
"description": "Optional custom data for tracking"
}
}
]
}
}
}
```
### Rule Fields
- **id** (required): Unique rule identifier
- **priority** (required): Evaluation priority (lower = higher precedence)
- **conditions** (required): Condition tree for evaluation
- **action** (required): Action identifier (informational, not evaluated by engine)
- **metadata** (optional): Custom metadata for tracing, compliance, or annotations. Will be included in evaluation results if present.
### Supported Operators
#### Comparison Operators
| `$equals` | Equal | `{"age": {"$equals": 18}}` |
| `$not-equals` | Not equal | `{"status": {"$not-equals": "inactive"}}` |
| `$greater-than` | Greater than | `{"score": {"$greater-than": 100}}` |
| `$less-than` | Less than | `{"price": {"$less-than": 50}}` |
| `$greater-than-or-equals` | Greater than or equal | `{"age": {"$greater-than-or-equals": 21}}` |
| `$less-than-or-equals` | Less than or equal | `{"count": {"$less-than-or-equals": 10}}` |
#### Membership Operators
| `$in` | Value in array | `{"tier": {"$in": ["Gold", "Platinum"]}}` |
| `$not-in` | Value not in array | `{"status": {"$not-in": ["banned", "suspended"]}}` |
#### String Operators
| `$contains` | Case-sensitive substring | `{"description": {"$contains": "premium"}}` |
| `$starts-with` | String starts with | `{"name": {"$starts-with": "Dr."}}` |
| `$ends-with` | String ends with | `{"email": {"$ends-with": "@company.com"}}` |
| `$regex` | Regular expression | `{"email": {"$regex": "^[a-z]+@[a-z]+\\.[a-z]+$"}}` |
### Logical Operators
**Implicit AND** - Multiple conditions in one object:
```json
{
"conditions": {
"age": {"$greater-than-or-equals": 18, "$less-than": 65},
"status": {"$equals": "active"}
}
}
```
**Explicit OR** - Use `$or`:
```json
{
"conditions": {
"$or": [
{"tier": {"$equals": "Platinum"}},
{"score": {"$greater-than": 1000}}
]
}
}
```
**Nested Logic**:
```json
{
"conditions": {
"$or": [
{"tier": {"$equals": "Platinum"}},
{
"tier": {"$equals": "Gold"},
"amount": {"$greater-than": 500}
}
]
}
}
```
## Performance
### Benchmarks
Run benchmarks:
```bash
cargo bench
```
### Optimization Features
- **Rust backend**: Native machine code performance
- **Zero allocations** in hot evaluation 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 evaluation (only for results)
## Development
```bash
# Run tests
cargo test
# Run Rust examples
cargo run --example demo
# Build documentation
cargo doc --no-deps --open
# Run Python tests
cd python/tests
python test_features.py
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
## Architecture
```
fast-decision/
├── src/ # Rust core engine
│ ├── lib.rs # Python bindings (PyO3)
│ ├── engine.rs # Rule evaluation 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](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](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.