Quickstart

This quickstart installs the blazerules Python module, verifies the import, and evaluates a small batch as both JSON and an Apache Arrow record batch.

In this Python path, BlazeRules runs as an embedded library. The application imports the module and calls the engine once per batch; no daemon or network endpoint is required. The same wheel also includes blazerules_agent for HTTP, stdin, and file-tail ingestion, plus the local blazerules_dashboard UI.

📘

Prerequisites

A Python 3.10+ interpreter is required. The PyPI wheel installs numpy and pyarrow automatically. Source builds additionally require a C++20 toolchain, CMake, Ninja, and vcpkg. On macOS arm64, install the build tools with:

Bash

brew install cmake ninja autoconf autoconf-archive automake libtool

For all platforms and presets, see Installation.

1. Install the Python module

pip install blazerules

The release wheel includes the blazerules and blazerules_io Python modules, ONNX Runtime scoring, and three command-line executables on PATH: blazerules for batch and stream evaluation, blazerules_agent, and blazerules_dashboard. See Installation for source-build flags and platform notes.

2. Smoke-test the import

Confirm the module loads and reports its SIMD backend:

python -c "import blazerules, blazerules_io; print(blazerules.__version__, blazerules.simd_backend())"

On Apple Silicon this typically prints the SIMD backend neon. On x86_64 hosts the backend is typically avx2 or scalar depending on the wheel and CPU.

cmake -S . -B cmake-build-release \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_TOOLCHAIN_FILE="$HOME/.vcpkg-clion/vcpkg/scripts/buildsystems/vcpkg.cmake" \
  -G Ninja

cmake --build cmake-build-release --target blazerules_core blazerules blazerules_io_py -j

export PYTHONPATH="$PWD/cmake-build-release"

./cmake-build-release/blazerules_agent --rules rules.yaml --input stdin --output stdout < events.ndjson

3. Evaluate the first batch

The engine compiles YAML rules once into an immutable plan, then evaluates a whole batch of records at a time. Rules can be loaded before a schema exists — the first evaluated batch samples the rule-referenced fields and infers their types.

The examples below use the sample rule file rules.yaml shipped in the repository root.

import blazerules

config = blazerules.EngineConfig()
config.output_detail = blazerules.OutputDetail.DECISIONS

engine = blazerules.RuleEngine(config)
engine.load_rules("rules.yaml")

payload = b"""
{"card_token":"card_1","amount":2500.0,"device_type":"emulator",
 "country_code":"US","account_age_days":2,"hour_of_day":1.5}
{"card_token":"card_2","amount":50.0,"device_type":"ios",
 "country_code":"GB","account_age_days":400,"hour_of_day":12}
"""

result = engine.evaluate_ndjson(payload)
print(result.n_records, result.n_matched)
print(result.decisions)
print(result.match_counts)

import pyarrow as pa
import blazerules

batch = pa.record_batch({
    "card_token": pa.array(["card_1", "card_2"]),
    "amount": pa.array([2500.0, 50.0], type=pa.float32()),
    "device_type": pa.array(["emulator", "ios"]),
    "country_code": pa.array(["US", "GB"]),
    "account_age_days": pa.array([2, 400], type=pa.int32()),
    "hour_of_day": pa.array([1.5, 12.0], type=pa.float32()),
})

engine = blazerules.RuleEngine()
engine.load_rules("rules.yaml")
result = engine.evaluate_batch(batch)
print(result.n_records, result.n_matched)
print(result.decisions)

Expected result

• result.n_records is 2 — the number of records in the batch.
• result.n_matched reports how many records matched at least one rule.
• result.decisions holds one decision per record (for example APPROVE or BLOCK), driven by the winning rule and the decision precedence ladder.
• result.match_counts reports how many records each rule matched.

The sample rules match the high-amount emulator record and leave the small, aged-account record unmatched. See Write the First Rule for a line-by-line rule and result walkthrough.

📘

JSON or Arrow?

Use evaluate_ndjson(bytes) for NDJSON/JSONL streams and
evaluate_json_array(bytes) when the batch is already one top-level JSON
array. Prefer evaluate_batch(arrow_batch) when upstream data is already
typed in Arrow — it skips JSON parsing entirely. Arrow batches may carry extra
columns or a different column order; BlazeRules projects rule-referenced
columns by name.

Troubleshooting first runs

❗

Common first-run errors

• ModuleNotFoundError: No module named 'blazerules' — PYTHONPATH does not point at the build directory. Set it to the directory containing the compiled module, such as $PWD/cmake-build-release.
• model_score rule rejected at load, or register_model(...) raises — the build was configured with BLAZERULES_ENABLE_ONNX=OFF. ONNX is ON by default; rebuild with it enabled to use model_score rules. See Installation.
• Rules fail to load — rule and schema activation are strict. Bad YAML, unknown fields, duplicate rule IDs, invalid regex, and missing lookup files all fail before activation. The raised error names the problem.

Related documentation