Metadata-Version: 2.4
Name: rulex-runtime
Version: 0.1.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)
runner = rulex_runtime.initialize()

# Load a pre-compiled .wasmu artifact
with open("rule.wasmu", "rb") as f:
    wasmu_bytes = f.read()

# Compile a .wasm module to a portable .wasmu artifact
with open("rule.wasm", "rb") as f:
    wasm_bytes = f.read()

version, wasmu_bytes = rulex_runtime.compile_wasm(wasm_bytes)

# Get a calculator for a specific interface and executor version
# Interface version is currently fixed to 1
calculator = runner.get_calculator((1, version), wasmu_bytes)

# 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)
```

## 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
```

## Supported Versions

`rulex_runtime.SUPPORTED_VERSIONS` is a `frozenset` of `(interface version, executor version)` tuples indicating which executor versions are available. The latest is always used for new compilations.

## License

Proprietary — Copyright © CoverStack Technologies. All rights reserved.

