Installation

BlazeRules can be installed from PyPI as a full-feature Python package or built from source with CMake and Ninja. This page covers pip install, source prerequisites, platform presets, every CMake option, and how to verify the result.

Install from PyPI

pip install blazerules

The release wheel is built full-feature. It contains the native blazerules extension, blazerules_io, ONNX model_score, Kafka/CDC/Arrow IPC/Avro/Protobuf/S3 IO, dashboard, agent, schema inference, decisions/scoring, windows, lookups, regex, CIDR, temporal, geo, vector similarity, and runtime-dispatched SIMD kernels. It also installs three command-line executables on your PATH — blazerules (the batch/stream CLI), 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

You also need a C++20 compiler and a vcpkg checkout for dependencies. The Arrow evaluation path and the Arrow examples require pyarrow in your 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

Replace CMAKE_TOOLCHAIN_FILE with the path to your own vcpkg checkout if 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 dramatically slower.

Presets

CMake presets are included for common production shapes. Pick the one matching your target platform:

   cmake --preset macos-arm64-release
   cmake --build --preset macos-arm64-release -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

Point Python at the build directory and confirm the module loads, reports its version, and reports the SIMD backend selected for your CPU:

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.

You can also smoke-test the local agent against 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. Bind it to 127.0.0.1 (localhost) unless you add your own network access controls.

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 your own image containing blazerules_agent and/or blazerules_dashboard, then point the chart's image.repository and image.tag values at that image. See Deployment.

Where to go next