FluxRules

FluxRules is a Python library for authoring rules and evaluating them against facts. It is loosely based on the concepts from Drools’ Phreak engine.

Use FluxRules to keep decision logic separate from application flow and evaluate rules consistently across facts.

Core Capabilities

• Evaluate a ruleset against facts using the top-level Python API.
• Run rule evaluation through FluxRules’ Phreak engine in stateless or streaming mode.
• Validate rulesets before evaluation.
• Retrieve evaluation explanations
• Use optional HTTP endpoints for evaluation, validation, explanations, and health checks.

Requirements

• Python 3.10+

Installation

For local development, clone the repository and install the project with uv:

git clone https://github.com/fluxrules/fluxrules.git
cd fluxrules
uv sync --extra dev

This creates the project environment and installs FluxRules with its development tools. To install the published package in a virtual environment managed by uv:

uv venv
uv pip install fluxrules

Install an optional extra in the checkout with uv sync, for example:

uv sync --extra api
uv sync --extra sql
uv sync --extra redis
uv sync --extra otel
uv sync --extra yaml
uv sync --extra cli
uv sync --extra docs
uv sync --extra all

For more details see the installation guide.

Your First Rule

from fluxrules import Rule, evaluate

rule = Rule(
    name="high_value_transaction",
    condition_dsl={"type": "condition", "field": "amount", "op": ">", "value": 5000},
    action="manual_review",
)

result = evaluate(rule, {"amount": 6000})

print(f"Fired rules: {result.fired_rules}")
print(f"Actions: {result.actions}")

Output:

Fired rules: [1]
Actions: ['manual_review']

Constructing a Rule does no I/O and evaluate() takes rules directly, so there is nothing to configure to get an answer. evaluate() also accepts a list of rules, or a named Ruleset.

Using the engine directly

from fluxrules import PhreakEngine, Rule

rule = Rule(
    name="high_value_transaction",
    domain="payments",
    condition_dsl={"type": "condition", "field": "amount", "op": ">", "value": 5000},
    action="manual_review",
    priority=100,
)

engine = PhreakEngine()
engine.load_rules([rule])

for fact in ({"amount": 6000}, {"amount": 10}):
    result = engine.evaluate(fact)
    print(fact, "->", result.fired_rules, result.actions)

To persist a rule, call rule.save(), or pass persist=True when constructing it. See the persistence guide.

API Server (Optional)

uv sync --extra api
uvicorn fluxrules.api.app:create_app --factory --reload

see API for more detail.

CLI (Optional)

uv sync --extra cli
fluxrules --help

Documentation

DOCS

Contributing

CONTRIBUTING & CODE OF CONDUCT

Security

SECURITY

License

LICENSE