rulex-runtime

Runtime engine powering the RuleX APIs. Executes pre-compiled WASM rule modules with high performance via LLVM-backed AOT compilation.

Features

• Execute compiled rule modules (.wasmu) against spreadsheet-like cell inputs
• AOT-compiled WASM via LLVM for maximum execution performance
• Multi-version executor support — artifacts are version-locked and multiple executor versions are bundled
• Thread-safe, concurrent execution
• Supports free-threaded Python (3.13t, 3.14t)

Requirements

• Linux x86_64 or aarch64
• Python 3.13+

Usage

import rulex_runtime

# Initialize the runner (optionally specify max concurrency and max memory for calculator cache)
runner = rulex_runtime.initialize()

# Load a pre-compiled .wasmu artifact
wasmu_path = pathlib.Path("rule.wasmu")

# Compile a .wasm module to a portable .wasmu artifact
wasm_bytes = pathlib.Path("rule.wasm").read_bytes()
wasmu_path.write_bytes(rulex_runtime.compile_wasm(wasm_bytes))

# Get the corresponding Calculator instance
calculator = runner.get_calculator(wasmu_path)

# Run a calculation
cell_ref = rulex_runtime.CellRef("Sheet1", "A1")
result = calculator.run(
    inputs={cell_ref: 42},
    outputs={cell_ref},
)
print(result.output)
print(result.cacheable)

# Validate inputs without specifying outputs
cacheable = calculator.validate(inputs={cell_ref: 42})
print(cacheable)

Concurrency

Calculator is thread-safe. calculator.run() is fully isolated and does not mutate any shared state, so it can be called concurrently from multiple threads with different inputs and outputs.

The concurrency parameter to initialize() controls the size of the executor thread pool. It should not exceed the total number of physical CPU cores on the machine. When running the runtime across multiple processes, ensure that the sum across all processes respects this constraint:

process_count × concurrency ≤ physical_cpu_count

The calculator_cache parameter to initialize() controls the LRU cache size of calculators. Calculator memory usage is estimated on a best-effort basis. So, it is advised to keep some margin based on the total memory available on the machine.

Supported Interfaces

rulex_runtime.SUPPORTED_INTERFACES is a frozenset of int indicating which interface versions are available.

Compilation

bytes returned by compile_wasm() are only compatible with the executor version (i.e. EXECUTOR_VERSION) used to compile it. Caller is advised to keep track of the EXECUTOR_VERSION for the returned binary.

If the content of path passed to get_calculator() does not correspond with the current executor version (EXECUTOR_VERSION), then InternalError will be raised.

License

Proprietary — Copyright © CoverStack Technologies. All rights reserved.