Zen Engine

0.54.0 · active · verified Fri Apr 17

Zen Engine is an open-source business rules engine implemented in Rust with Python bindings, designed for high-performance decision-making. It allows users to define complex business logic using a DMN-like JSON/YAML schema for decisions and flows. As of version 0.54.0, it leverages a Rust core for efficiency and provides a Pythonic interface for integration. It is actively maintained with frequent updates.

Common errors

```
zen_engine.ZenSchemaError: Invalid decision schema:
```
cause Your decision or flow definition JSON/YAML does not conform to the expected schema, often due to changes introduced in v0.50.0 or malformed structure.

fix Review the official Zen Engine documentation for the correct schema structure. Pay close attention to required fields, data types, and the structure of expressions. Validate your JSON/YAML carefully.
```
AttributeError: 'dict' object has no attribute 'result'
```
cause You are trying to access `result.result` (or similar) on what you expect to be a `ZenResult` object, but `engine.evaluate()` returned a plain dictionary, which is no longer the case since v0.50.0.

fix This error likely means your code was written for Zen Engine versions prior to 0.50.0. Update your result access to use the `ZenResult` object's properties: `result_obj.result`, `result_obj.success`, `result_obj.error`.
```
ModuleNotFoundError: No module named 'zen_engine'
```
cause The `zen-engine` package is not installed in your current Python environment, or your Python interpreter path is incorrect.

fix Install the package using pip: `pip install zen-engine`. If already installed, ensure your IDE or script is using the correct Python environment where the package is installed.

Warnings

breaking The internal schema for Decision and Flow definitions underwent significant changes in version 0.50.0. Older rule definitions might no longer be valid and will fail validation.
Fix: Review and update your JSON/YAML rule definitions to conform to the new schema introduced in v0.50.0. Refer to the official Zen Engine documentation for the latest schema structure.
breaking The return type of `engine.evaluate()` changed from a direct dictionary to a `ZenResult` object starting from version 0.50.0. Direct dictionary access (e.g., `result['result']`) will now raise an `AttributeError`.
Fix: Update your code to access evaluation results via the `ZenResult` object's properties, such as `result.result` for the successful output, `result.success` to check for success, and `result.error` for error details.
gotcha When initializing `ZenEngine` for advanced use cases (e.g., loading external resources), the `resources` argument was deprecated and replaced by `loader`.
Fix: If you were passing a dictionary of resources to `ZenEngine()`, you now need to provide a `loader` object instead. The `loader` is an interface that the engine uses to fetch external DMNs/Flows/etc. Consult the documentation for implementing a custom loader.
gotcha Zen Engine expressions use a custom expression language similar to DMN FEEL. Familiarity with JavaScript-like syntax for string manipulation, comparisons, and conditional logic is helpful, but specific functions and operators may differ.
Fix: Always refer to the official Zen Engine documentation for the precise syntax and available functions within its expression language. Do not assume full compatibility with JavaScript or other common expression languages.

Install

pip install zen-engine Install latest version

Imports

ZenEngine
```
from zen_engine import ZenEngine
```
The primary class for creating an engine instance and evaluating rules.
ZenResult
```
from zen_engine import ZenResult
```
The result object returned by the evaluate method since v0.50.0.

Quickstart

This quickstart demonstrates how to initialize the `ZenEngine`, define a basic decision rule using its JSON schema, and evaluate it with input context. It also shows how to access the result from the `ZenResult` object.

from zen_engine import ZenEngine

# Define a simple decision rule in DMN-like JSON format
decision_rule = {
    "name": "Welcome Message Decision",
    "kind": "Decision",
    "version": 1,
    "inputs": {
        "name": "text"
    },
    "output": "text",
    "expressions": [
        {
            "kind": "Literal",
            "content": "'Hello, ' + name + '!'"
        }
    ]
}

# Initialize the Zen Engine
engine = ZenEngine()

# Evaluate the decision with context data
context = {"name": "World"}
result = engine.evaluate(decision_rule, context)

# Access the result using the ZenResult object
if result.success:
    print(f"Decision Result: {result.result}")
else:
    print(f"Decision Error: {result.error}")

# Example with a different name
context_2 = {"name": "Alice"}
result_2 = engine.evaluate(decision_rule, context_2)
print(f"Decision Result for Alice: {result_2.result}")

view raw JSON →