Metadata-Version: 2.4
Name: rulex-runtime
Version: 1.0.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading
Classifier: Typing :: Typed
Requires-Dist: pydantic>2,<3
Summary: Runtime engine to power RuleX APIs
Author-email: CoverStack Technologies <devops@coverstack.in>
License: Proprietary
Requires-Python: >=3.13
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://coverstack.in/rulex/

# 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

```python
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.

