Quickstart

This page gets you from install to a first evaluated batch in about five minutes. You will install the blazerules Python module, run a smoke import, then evaluate a small batch of records two ways: as JSON and as an Apache Arrow record batch.

On the Python quickstart path shown here, BlazeRules is a library — you build it, import it, and call the engine once per batch from your own process, with no daemon or network endpoint to start. (The same wheel also ships blazerules_agent, a long-running HTTP/stdin/file-tail daemon, and blazerules_dashboard, a local UI, if you want those.)

📘

Prerequisites

A Python 3.10+ interpreter. The PyPI wheel installs the Python runtime dependencies (numpy and pyarrow) automatically. For source builds you also need a C++20 toolchain, CMake, Ninja, and vcpkg. On macOS arm64, install 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 your PATH — blazerules (the batch/stream CLI), 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 your 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)

What you should see

• 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 high-amount emulator record is the kind of record the sample rules are designed to catch; the small, aged-account record is not. For a line-by-line walkthrough of a single rule and its output fields, see Write Your First Rule.

📘

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 your 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. Re-run the export PYTHONPATH="$PWD/cmake-build-release" line from the same shell, or set it to wherever you built the module.
• 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.

Where to go next