Installation

BlazeRules is available as a Python wheel, native release archive, or source build. This page covers package installation, source prerequisites, platform presets, CMake options, and verification.

Install from PyPI

pip install blazerules

The release wheel contains the native blazerules extension, blazerules_io, ONNX model_score, Kafka/CDC/Arrow IPC/Avro/Protobuf/S3 IO, dashboard, agent, schema inference, decisions and scoring, windows, lookups, regex, CIDR, temporal and geo operators, vector similarity, and runtime-dispatched SIMD kernels. It also installs three command-line executables on the active PATH: blazerules (batch and stream operations), blazerules_agent, and blazerules_dashboard. numpy and pyarrow are declared Python runtime dependencies and are installed by pip.

Native archives with the same three binaries for non-Python use are published on GitHub Releases for the platforms currently built by CI:

• Linux x86_64
• Linux aarch64
• macOS arm64

Those archives contain blazerules, blazerules_agent, and blazerules_dashboard. They are built from the tagged GitHub source revision by the Build release binaries workflow.

The blazerules executable is the full native batch/stream CLI. It can validate rules, evaluate NDJSON/JSON/Arrow IPC/Parquet/CSV/Avro/Protobuf/Debezium inputs, run Kafka microbatch loops, and launch backtests without Python:

blazerules info
blazerules eval --rules rules.yaml --input ndjson --path events.ndjson --output summary
blazerules stream kafka --rules rules.yaml --brokers localhost:9092 --input-topic transactions --format avro --schema transaction.avsc

Prerequisites

On macOS arm64 — the reference machine — install the build tools with Homebrew:

brew install cmake ninja autoconf autoconf-archive automake libtool

A source build requires a C++20 compiler and a vcpkg checkout for dependencies. Arrow evaluation examples require pyarrow in the active Python environment.

Standard source build

From the repository root, configure and build the core library and Python modules:

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 blazerules_cli -j

Set CMAKE_TOOLCHAIN_FILE to the active vcpkg checkout when it is not under $HOME/.vcpkg-clion.

🚧

Always build Release

Use -DCMAKE_BUILD_TYPE=Release. The measured throughput characteristics described in the Performance Model assume an optimized Release build. Debug builds are not representative of production throughput.

Presets

CMake presets are included for common production targets. Select the preset matching the target platform:

cmake --preset macos-arm64-release
cmake --build --preset macos-arm64-release -j

cmake --preset linux-x86_64-release-dispatch
cmake --build --preset linux-x86_64-release-dispatch -j

cmake --preset cloud-portable-release
cmake --build --preset cloud-portable-release -j

cmake --preset windows-x64-release-dispatch
cmake --build --preset windows-x64-release-dispatch -j

Portable Linux, Windows, and cloud builds do not compile generic code with global AVX flags. ISA-specific files are compiled separately and selected at runtime, so the same binary runs across a range of CPUs and picks the best available kernel. Linux x86_64 builds include AVX2 and optional AVX-512 objects when the compiler supports them; macOS arm64 uses the AArch64 NEON backend.

CMake options

The following options control source-build features. Defaults are full-feature so a normal source build matches the PyPI release policy.

📘

IO module

The Kafka, CDC, Arrow IPC, Avro, and Protobuf connectors live in a separate blazerules_io module. The full wheel and default source build include it; custom lean builds can still disable it with -DBLAZERULES_IO=OFF.

To build a local full-feature development tree:

cmake -S . -B cmake-build-release \
  -DCMAKE_BUILD_TYPE=Release \
  -DBLAZERULES_ENABLE_ONNX=ON \
  -DBLAZERULES_IO=ON \
  -DBLAZERULES_IO_KAFKA=ON \
  -DBLAZERULES_IO_AVRO=ON \
  -DBLAZERULES_IO_PROTOBUF=ON \
  -DBLAZERULES_IO_S3=ON \
  -DBLAZERULES_DASHBOARD=ON \
  -DBLAZERULES_AGENT=ON \
  -DBLAZERULES_NATIVE_TUNE=ON \
  -DBLAZERULES_X86_AVX2=ON \
  -DBLAZERULES_X86_AVX512=ON \
  -G Ninja

Verify the build

Add the build directory to PYTHONPATH, then verify module loading, version reporting, and runtime SIMD selection:

export PYTHONPATH="$PWD/cmake-build-release"
python - <<'PY'
import blazerules
import blazerules_io
print("version:", blazerules.__version__)
print("simd backend:", blazerules.simd_backend())
print("cpu features:", blazerules.cpu_features_summary())
print("io kafka:", blazerules_io.has_kafka)
PY

On Apple Silicon the SIMD backend is typically neon. On x86_64 the backend is typically avx2 or scalar. The YAML compatibility level is available as blazerules.RULE_YAML_COMPATIBILITY and tracks the 2.x rule format.

Agent smoke test with NDJSON from stdin:

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

Executables: CLI, dashboard, and agent

Three command-line executables ship with the full-feature build: blazerules (the batch/stream CLI shown above), blazerules_dashboard, and blazerules_agent.

The dashboard is a local, read-only UI:

cmake --build cmake-build-release --target blazerules_dashboard -j
./cmake-build-release/blazerules_dashboard --host 127.0.0.1 --port 9470 --rules rules.yaml

❗

The dashboard is unauthenticated

The dashboard is read-only and has no authentication. Keep the default 127.0.0.1 bind unless external authentication and network access controls are configured.

The agent is a local multi-input ingest process (HTTP, file-tail, stdin) driven by a top-level instances: block in the rule file:

cmake --build cmake-build-release --target blazerules_agent -j

Containers and Kubernetes

The repository includes an optional Helm chart under charts/.

The repository does not ship a Dockerfile. Build an image containing blazerules_agent and/or blazerules_dashboard, then set the chart's image.repository and image.tag values to that image. See Deployment.

Related documentation