API and CLI Values Reference

This page is the compact reference for values you can pass to BlazeRules from the command line or Python.

📘
--input chooses the input type
blazerules_agent --input accepts stdin, file_tail, or http. --source is only a free-form metadata label written into wrapped log records and output; it is not an input selector.

`blazerules_agent` CLI

Use --config agent.yaml for multiple instances, or pass single-instance flags directly.

Argument	Values	Default	Meaning
`--config`	path or `s3://bucket/key`	none	Load one or more `instances:` from YAML.
`--name`	string	`default`	Instance label.
`--rules`	path or `s3://bucket/key`	required	Rule YAML for this instance.
`--input`	`stdin`, `file_tail`, `http`	`stdin`	Input adapter.
`--path`	path	none	File path for `file_tail`.
`--host`	IP or hostname	`127.0.0.1`	HTTP bind host.
`--port`	integer	`9480`	HTTP bind port.
`--batch-size`	integer	`2048`	Records buffered before a size flush.
`--flush-ms`	integer	`1000`	Milliseconds before flushing a partial batch.
`--output`	`stdout`, `ndjson`	`stdout`	Decision output sink.
`--output-path`	path	none	NDJSON decision path when `--output ndjson`.
`--service`	string	`--name`	Metadata label.
`--source`	string	`log`	Metadata label, not an input selector.
`--dedupe-key`	field name, repeatable	none	Enables local de-dupe using one or more fields.
`--dedupe-ttl-seconds`	integer	`86400`	How long duplicate keys stay suppressed.

blazerules_agent \
  --rules rules.yaml \
  --input http \
  --host 127.0.0.1 \
  --port 9480 \
  --batch-size 4096 \
  --flush-ms 50 \
  --output ndjson \
  --output-path decisions.ndjson \
  --service payments-api \
  --source http-json \
  --dedupe-key event_id

Python equivalent: start the same agent process

import subprocess

agent = subprocess.Popen([
    "blazerules_agent",
    "--rules", "rules.yaml",
    "--input", "http",
    "--host", "127.0.0.1",
    "--port", "9480",
    "--batch-size", "4096",
    "--flush-ms", "50",
    "--output", "ndjson",
    "--output-path", "decisions.ndjson",
    "--service", "payments-api",
    "--source", "http-json",
    "--dedupe-key", "event_id",
])

Agent `instances:` YAML

The same settings can be placed in YAML. A top-level instances: list starts one thread per instance.

YAML key	Values	Default	Meaning
`instances[].name`	string	`default`	Instance label.
`instances[].rules`	path or `s3://bucket/key`	required	Rule YAML.
`instances[].batch_size`	integer	`2048`	Size flush threshold.
`instances[].flush_ms`	integer	`1000`	Time flush threshold.
`instances[].service`	string	instance name	Service metadata label.
`instances[].source`	string	`log`	Source metadata label.
`instances[].input.type`	`stdin`, `file_tail`, `http`	`stdin`	Input adapter.
`instances[].input.path`	path	none	Required for `file_tail`.
`instances[].input.host`	host	`127.0.0.1`	HTTP bind host.
`instances[].input.port`	integer	`9480`	HTTP bind port.
`instances[].output.type`	`stdout`, `ndjson`	`stdout`	Decision sink.
`instances[].output.path`	path	none	Required for `ndjson`.
`instances[].dedupe.enabled`	`true`, `false`	`false`	Enable local duplicate suppression.
`instances[].dedupe.key_fields`	list of field names	none	Duplicate key fields.
`instances[].dedupe.ttl_seconds`	integer	`86400`	Duplicate suppression TTL.

`blazerules_dashboard` CLI

Argument	Values	Default	Meaning
`--host`	IP or hostname	`127.0.0.1`	HTTP bind host.
`--port`	integer	`9470`	Dashboard port.
`--poll-ms`	integer	`1000`	Poll interval for watched files and metrics.
`--tail-lines`	integer	`5000`	Bounded recent-line buffer per log file.
`--decision-log`	path	none	Compact decision NDJSON to inspect.
`--dead-letter-log`	path	none	Dead-letter NDJSON to inspect.
`--metrics-url`	URL	none	Prometheus exposition URL.
`--results-jsonl`	path	none	Stress matrix benchmark JSONL.
`--rules`	path	none	Active rules YAML for validation and visualizer.
`--candidate-rules`	path	none	Candidate rules YAML for diff/validation.
`--rules-history-dir`	path	none	Directory of previous YAML versions.

Python module constants and enums

Name	Values
`blazerules.ColumnType`	`FLOAT32`, `FLOAT64`, `INT32`, `INT64`, `CATEGORICAL`, `ENTITY_KEY`, `TIMESTAMP_MS`, `BOOLEAN`, `STRING`
`blazerules.ActionType`	`APPROVE`, `FLAG`, `REVIEW`, `BLOCK`, `SCORE`
`blazerules.RuleFileFormat`	`YAML`, `JSON`
`blazerules.OutputDetail`	`DECISIONS`, `BITMASKS`
`blazerules.IngestErrorMode`	`SKIP_AND_COUNT`, `SKIP_TO_DEAD_LETTER`, `HARD_FAIL`
`blazerules.TypeMismatchMode`	`NULL_ON_TYPE_ERROR`, `COERCE`, `HARD_FAIL_TYPE`
`blazerules.SimdBackend`	`SCALAR`, `NEON`, `SSE2`, `AVX2`, `AVX512`

`EngineConfig`

Attribute	Values	Default	Meaning
`batch_size`	integer	`10000`	Preferred internal batch size.
`parallel_threshold`	integer	`1000`	Row threshold before parallel execution is considered.
`eval_thread_count`	integer	`0`	`0` means automatic worker count.
`output_detail`	`OutputDetail.DECISIONS`, `OutputDetail.BITMASKS`	build default	Decision-only output or detailed bitmasks.
`ingest_error_mode`	`SKIP_AND_COUNT`, `SKIP_TO_DEAD_LETTER`, `HARD_FAIL`	`SKIP_AND_COUNT`	Bad-record policy.
`type_mismatch_mode`	`NULL_ON_TYPE_ERROR`, `COERCE`, `HARD_FAIL_TYPE`	`NULL_ON_TYPE_ERROR`	Type drift policy after schema binding.
`max_error_samples`	integer	`16`	Max bad-record samples kept in `BatchResult`.
`decision_log_path`	string path	empty	Empty disables engine-level decision logging.
`dead_letter_path`	string path	empty	Dead-letter output path for skipped records.
`max_window_entities`	integer	`10000000`	Window state capacity hint.
`arena_size_bytes`	integer	`8388608`	Per-worker arena size.
`max_dict_size_per_column`	integer	`100000`	Dictionary cap for non-entity categoricals.
`enable_selection_vectors`	bool	`true`	Use survivor-index execution for selective predicates.
`selection_vector_threshold`	float	`0.20`	Survivor fraction below which index execution becomes useful.
`enable_adaptive_predicate_ordering`	bool	`true`	Order cheap/high-rejection predicates first.
`enable_no_validity_fast_path`	bool	`true`	Skip validity bitmap work for known non-null columns.
`enable_prefetch`	bool	`false`	Enable explicit prefetch in long scans.
`enable_thread_affinity`	bool	`false`	Best-effort worker affinity.
`result_buffer_reuse`	bool	`true`	Reuse output buffers across evaluations.
`simd_backend_override`	`auto`, `scalar`, `neon`, `sse2`, `avx2`, `avx512`	`auto`	Runtime SIMD backend override.
`enable_avx512`	bool	`false`	Make AVX-512 eligible during auto selection.
`hot_reload_poll_seconds`	integer	`5`	Default hot-reload polling interval.
`hot_reload_validate_conflicts`	bool	`true`	Analyze conflicts before hot-reload activation.
`hot_reload_keep_previous_on_failure`	bool	`true`	Keep old rules active when reload fails.
`trace_sample_rate`	float	`0.05`	Trace sampling rate when tracing is enabled by the native build.

`RuleEngine` methods

Method	Main arguments	Returns / effect
`RuleEngine()`	optional `EngineConfig`; optional explicit schema	Creates an engine. Omit schema to infer from the first batch.
`load_rules(path)`	local path or `s3://...`	Loads, validates, compiles, and activates rules.
`load_rules_from_string(text, format=YAML)`	YAML/JSON text	Compiles rules from memory.
`reload_rules_now(path)`	local path or `s3://...`	Compile-and-swap immediately if valid.
`enable_hot_reload(path, poll_interval_seconds=5)`	path and polling seconds	Starts background reload checks.
`stop_hot_reload()`	none	Stops the hot-reload thread.
`hot_reload_status()`	none	Returns `HotReloadStatus`.
`evaluate_ndjson(payload)`	bytes-like NDJSON	Evaluates one JSON batch.
`evaluate_ndjson_padded(payload, logical_size)`	padded bytes-like NDJSON	Evaluates already padded NDJSON without copying the padding.
`evaluate_messages(messages)`	sequence of JSON strings/bytes	Convenience path for smaller integrations.
`evaluate_batch(batch)`	`pyarrow.RecordBatch`	Evaluates typed Arrow data.
`evaluate_ndjson_file(path)`	local path or `s3://...`	Reads/evaluates NDJSON file.
`create_shards(shard_count)`	integer	Returns partition-affine engine shards.
`evaluate_partition_messages(partition_id, messages)`	partition id, JSON messages	Routes to partition-local state.
`evaluate_partition_ndjson_padded(partition_id, payload, logical_size)`	partition id, payload	Partition-aware NDJSON evaluation.
`evaluate_partition_batch(partition_id, batch)`	partition id, Arrow batch	Partition-aware Arrow evaluation.
`register_model(name, path)`	model name, ONNX path or `s3://...`	Registers a model used by `model_score`.
`reset_window_state()`	none	Clears in-memory window state.
`backtest(parquet_path, rules_a, rules_b, label_column=None)`	path(s), two rule sets	Runs offline comparison.
`analyze_conflicts(rules_path)`	rules path	Returns `ConflictReport`.
`enable_metrics()` / `reset_metrics()` / `metrics_snapshot()`	none	In-process metrics.

`BatchResult`

Attribute or method	Meaning
`n_records`, `n_matched`	Batch size and matched-row count.
`decisions`, `decision_codes`, `decision_label_map`	Per-row decision labels or compact integer codes.
`scores`, `risk_bands`, `winning_rule_ids`	Per-row scoring outputs.
`match_counts`	Rule ID to fire count.
`matched_indices`	NumPy array of all matched row indices.
`indices_for_decision(label)`	NumPy indices for one decision label.
`indices_for_not_decision(label)`	NumPy indices for all other labels.
`grouped_decision_indices()`	Dict of decision label to NumPy index array.
`grouped_winning_rule_indices()`	Dict of winning rule id to NumPy index array.
`indices_for_rule(rule_id)`	NumPy indices for a rule; requires rule bitmasks.
`result[rule_id]`	Boolean NumPy mask; requires `OutputDetail.BITMASKS`.
`decision_codes_buffer()`, `matched_indices_buffer()`, `rule_bitmask_buffer(rule_id)`	Zero-copy memoryview buffers for high-throughput routing.
`messages_processed`, `messages_skipped`, `error_counts`, `error_samples`, `last_ingest_error`	Ingest diagnostics.
`timing`	Dict of internal timing fields in milliseconds.

`blazerules_io`

Name	Values / arguments	Meaning
`has_kafka`, `has_avro`, `has_protobuf`	bool	Runtime capability flags for optional IO features.
`FileFormat`	`AUTO`, `ARROW_IPC`, `PARQUET`, `CSV`, `NDJSON`	File reader format selector.
`read_ndjson_bytes(path)`	local path or `s3://...`	Reads exact NDJSON bytes.
`read_record_batches(path, format="auto", batch_size=65536)`	local/S3 path	Reads Arrow IPC, Parquet, CSV, or NDJSON into Arrow batches.
`ArrowIpcDecoder.decode_batch(frames)`	sequence of frames	Decodes binary Arrow IPC to one Arrow batch.
`AvroDecoder(schema_json).decode_batch(frames)`	sequence of Avro records	Decodes Avro directly to Arrow when Avro support is built.
`ProtobufDecoder(descriptor_set_bytes, message_type).decode_batch(frames)`	sequence of protobuf records	Decodes Protobuf directly to Arrow when Protobuf support is built.
`unwrap_debezium(messages, op_field="__op")`	JSON CDC messages	Converts Debezium envelopes to NDJSON bytes.
`KafkaConsumer(brokers, group_id, topics, conf={})`	Kafka connection settings	Polls Kafka batches or records.
`KafkaProducer(brokers, conf={})`	Kafka connection settings	Produces decision events.
`StreamRunConfig`	see below	C++-owned Kafka consume/evaluate/produce loop config.
`run_stream(engine, config)`	`RuleEngine`, `StreamRunConfig`	Runs the native Kafka microbatch loop.

StreamRunConfig fields:

Attribute	Type	Meaning
`brokers`	string	Kafka bootstrap servers.
`group_id`	string	Consumer group.
`input_topics`	list of strings	Topics to consume.
`output_topic`	string	Topic for compact decisions.
`consumer_conf`, `producer_conf`	dict string to string	Extra librdkafka settings.
`batch_size`	integer	Max records per engine evaluation.
`poll_timeout_ms`	integer	Poll wait.
`flush_timeout_ms`	integer	Producer flush wait.
`max_messages`, `max_batches`	integer	Local run limits; leave at zero for unbounded.
`commit_offsets`	bool	Commit offsets after a batch is processed.

AWS and S3 helpers

Python function	Meaning
`set_aws_profile(profile, clear_env_credentials=True)`	Use an AWS CLI profile and optionally ignore stale key env vars.
`clear_aws_profile()` / `current_aws_profile()`	Clear or inspect profile selection.
`set_aws_region(region)`	Set region for `s3://` reads.
`clear_aws_region()` / `current_aws_region()`	Clear or inspect region selection.
`set_aws_endpoint_url(endpoint_url)`	Set S3-compatible endpoint for MinIO, R2, or LocalStack.
`clear_aws_endpoint_url()` / `current_aws_endpoint_url()`	Clear or inspect endpoint.
`set_aws_credentials(access_key_id, secret_access_key, session_token="", region="")`	Set process credentials for short-lived local scripts.
`clear_aws_credentials()`	Remove process AWS key variables.

Equivalent environment variables:

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

Rule values

The rule operator list is maintained in Operator Reference. The production shape of a full rule file is in Production YAML Guide.

--input chooses the input type

blazerules_agent CLI

Agent instances: YAML

blazerules_dashboard CLI

Python module constants and enums

EngineConfig

RuleEngine methods

BatchResult

blazerules_io

AWS and S3 helpers

Rule values

`--input` chooses the input type

`blazerules_agent` CLI

Agent `instances:` YAML

`blazerules_dashboard` CLI

`EngineConfig`

`RuleEngine` methods

`BatchResult`

`blazerules_io`