Configuration Reference

This page is the reference for tuning the engine at three layers: runtime (an EngineConfig you pass when constructing a RuleEngine), build time (CMake options that decide which features and SIMD kernels are compiled in), and environment (variables that point the engine at AWS for s3:// reads).

📘

Defaults are production-safe

Every option below has a default chosen for correctness over raw speed. You can run BlazeRules with EngineConfig() and no overrides; tune only the values you have a measured reason to change.

EngineConfig options

EngineConfig is constructed empty and configured by attribute, then handed to a RuleEngine. All six options below are surfaced on the config object.

🚧

output_detail integer values shifted — reference it by name

OutputDetail.COUNTS and OutputDetail.CODES were added before DECISIONS and BITMASKS in the underlying enum, so the raw integer values shifted: DECISIONS and BITMASKS used to be 0 and 1 and are now 2 and 3. Any config that serialized output_detail as a raw integer instead of the named constant — EngineConfig::OUTPUT_DECISIONS in C++, blazerules.OutputDetail.DECISIONS in Python, or a bare number in a hand-rolled config file — will silently resolve to a different, cheaper output tier after upgrading. Always set output_detail by name, never by number. See Decisions & Scoring for what each tier materializes.

Constructing an engine with a config

   import blazerules

   config = blazerules.EngineConfig()
   config.output_detail = blazerules.OutputDetail.DECISIONS
   config.ingest_error_mode = blazerules.IngestErrorMode.SKIP_AND_COUNT
   config.type_mismatch_mode = blazerules.TypeMismatchMode.NULL_ON_TYPE_ERROR
   config.simd_backend_override = "auto"
   config.enable_avx512 = False

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

📘

Three constructors

RuleEngine() uses defaults and infers schema from the first batch. RuleEngine(config) applies your tuning but still infers schema. RuleEngine(schema, config) binds an explicit schema up front — use it when you want deterministic types instead of inference. See Troubleshooting for why explicit schema avoids the "everything inferred as INT32" surprise.

Setting these from the CLI

The runtime-layer options map directly to blazerules eval flags, so a single-run CLI invocation can apply the same tuning without Python:

blazerules ... --config config.yaml accepts the same values under an engine: block; explicit flags override anything set in the config file.

Build-time CMake options

These options are set when you configure the build. They decide which features (ONNX, IO connectors, dashboard/agent) and which SIMD kernels are compiled into the library. Defaults are full-feature.

🚧

BLAZERULES_IO_KAFKA only matters when BLAZERULES_IO=ON

The Kafka, Avro, and Protobuf sub-options have no effect unless the IO module is built with -DBLAZERULES_IO=ON. The release wheel and default source build enable it. If a connector or decoder is missing at runtime, check both flags. See Troubleshooting for the has_kafka / has_avro / has_protobuf capability checks.

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. For ready-made build shapes per platform, use the presets documented in Deployment.

Environment variables

The engine reads exact-object s3://bucket/key URIs (rules, lookup CSVs, ONNX models) through the AWS CLI cache path. You can point it at a profile, region, and endpoint with environment variables — the equivalent of set_aws_profile() / set_aws_region() / set_aws_endpoint_url().

export BLAZERULES_AWS_PROFILE=personal
export BLAZERULES_AWS_REGION=us-east-1
export BLAZERULES_AWS_ENDPOINT_URL=http://127.0.0.1:9000

BLAZERULES_AWS_ENDPOINT_URL is useful for S3-compatible stores (for example, a local MinIO). When deploying, supply these through your platform's secret mechanism rather than committing them — see Deployment.

SIMD diagnostics

Two read-only helpers report what backend the engine selected and what the CPU advertises. Use them when filing an issue or verifying a build behaves as expected on a given host.

import blazerules

print(blazerules.simd_backend())          # e.g. "neon" on an Apple M1
print(blazerules.cpu_features_summary())  # human-readable CPU feature list

On the reference machine (Apple M1) simd_backend() reports neon. On a cloud x86_64 host with AVX2 compiled in, it typically reports avx2. If you pinned simd_backend_override, this reflects the pinned value where supported.

🚧

AVX-512 auto-selection is still runtime-gated

AVX-512 kernels are compiled in full builds, but the engine still checks CPU and OS support before selecting them. Some server CPUs reduce frequency under wide vectors, which can make AVX-512 slower than AVX2 for a mixed rule workload. Benchmark your own ruleset on your own hardware before forcing it.

Where to go next