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.

BlazeRules is a library, not a hosted service — there is no daemon or network endpoint to start. You build it, import it, and call the engine once per batch from your own process.

📘

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 blazerules, blazerules_io, ONNX Runtime scoring, the dashboard executable, and the agent executable. 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 prints the library version 0.1.0 and 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_driver -j

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

./cmake-build-release/blazerules_driver rules.yaml

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 raw JSON streams. 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