https://github.com/hbmartin/mathjs-to-func
Compile serialized math.js expression trees into fast, reusable Python callables. Optional parse extra.
https://github.com/hbmartin/mathjs-to-func
ast compiler expression-evaluator expression-parser expressions formula formula-parser formulae mathjs numpy
Last synced: 12 days ago
JSON representation
Compile serialized math.js expression trees into fast, reusable Python callables. Optional parse extra.
- Host: GitHub
- URL: https://github.com/hbmartin/mathjs-to-func
- Owner: hbmartin
- License: apache-2.0
- Created: 2025-10-31T12:37:49.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-10-31T15:20:06.000Z (7 months ago)
- Last Synced: 2025-10-31T15:30:27.826Z (7 months ago)
- Topics: ast, compiler, expression-evaluator, expression-parser, expressions, formula, formula-parser, formulae, mathjs, numpy
- Language: Python
- Homepage:
- Size: 60.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# mathjs-to-func
[](https://pypi.org/project/mathjs-to-func/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/ambv/black)
[](https://github.com/astral-sh/ty)
[](https://github.com/hbmartin/mathjs-to-func/actions/workflows/ci.yml)
[](https://deepwiki.com/hbmartin/mathjs-to-func)
A tiny Python library that compiles serialized [math.js](https://mathjs.org/) expression trees into fast, reusable Python callables. The generated function respects dependency ordering, validates inputs, and mirrors a practical subset of math.js operators, constants, comparisons, conditionals, and numeric functions.
## Key Features
- Execute without reparsing or repeatedly walking the JSON graph.
- Detect dependency cycles and missing identifiers early.
- Keep execution sandboxed by compiling a controlled Python AST.
- Work well with scalars or NumPy arrays for vectorised workloads.
- Resolve common math.js constants like `pi`, `e`, `tau`, `NaN`, and `Infinity`.
## Installation
The project uses [uv](https://github.com/astral-sh/uv) for dependency and virtualenv management. From the repository root:
```bash
uv add mathjs-to-func
```
An optional `parse` extra installs a JSON-to-math.js parser powered by Pydantic:
```bash
uv add mathjs-to-func --extra parse
```
## Compiling A Function
```python
from mathjs_to_func import build_evaluator, to_dot, to_string
def main():
mathjs_payload = {
"expressions": {
# z = (x + y) / 2
"sum_xy": {
"type": "OperatorNode",
"fn": "add",
"args": [
{"type": "SymbolNode", "name": "x"},
{"type": "SymbolNode", "name": "y"},
],
},
"mean": {
"type": "OperatorNode",
"fn": "divide",
"args": [
{"type": "SymbolNode", "name": "sum_xy"},
{"type": "ConstantNode", "value": "2", "valueType": "number"},
],
},
},
"inputs": ["x", "y"],
"target": "mean",
}
evaluator = build_evaluator(**mathjs_payload, include_source=True)
result = evaluator({"x": 10, "y": 6})
print(result) # -> 8.0
# Introspection helpers
print(evaluator.__mathjs_required_inputs__) # ('x', 'y')
print(evaluator.__mathjs_evaluation_order__) # ('sum_xy', 'mean')
print(evaluator.__mathjs_inputs_referenced_per_target__) # {'mean': ('x', 'y')}
print(evaluator.__mathjs_source__) # Generated Python source
print(to_string(mathjs_payload)) # sum_xy / 2
print(to_dot(mathjs_payload)) # Dependency graph
```
### Parameters
`build_evaluator` accepts keyword parameters (or a single `payload` mapping containing the same keys):
| Argument | Type | Description |
|---------------|------------------------------------|-------------|
| `expressions` | `Mapping[str, Mapping[str, Any]]` | math.js AST JSON keyed by expression id. Each id becomes a local variable in the compiled function. |
| `inputs` | `Iterable[str]` | Whitelisted identifiers that may be supplied when the function is invoked. |
| `target` | `str \| Sequence[str]` | Name of the expression to return, or multiple expression names to return as a `dict[str, Any]`. |
| `config` | `EvalConfig \| Mapping[str, object]` (optional) | Per-evaluator runtime options. `rel_tol`, `abs_tol`, and math.js-style `epsilon` control comparison tolerances; `comparison` selects `"mathjs"`, `"numpy"`, or `"strict"` equality semantics; `result_dtype` selects `"auto"`, `"numpy"`, or `"python"` scalar demotion policy. |
| `compile_cache` | `bool` (optional) | Reuse compiled functions through an opt-in structural LRU cache. |
| `compile_cache_maxsize` | `int \| None` (optional) | Cache size when `compile_cache=True`; defaults to `128`, and `None` makes the cache unbounded. |
| `include_source` | `bool` (optional) | Attach executable generated Python source code as `__mathjs_source__` on the returned callable. |
The returned callable always expects a single mapping argument with the provided inputs. It returns the evaluated `target` value when `target` is a string, or a `dict[str, Any]` in the requested target order when `target` is a sequence, and may be reused across invocations.
When `target` is a sequence, the callable returns a mapping in the requested target order:
```python
exprs = {
"low": {
"type": "OperatorNode",
"fn": "subtract",
"args": [
{"type": "SymbolNode", "name": "x"},
{"type": "ConstantNode", "value": "2", "valueType": "number"},
],
},
"high": {
"type": "OperatorNode",
"fn": "add",
"args": [
{"type": "SymbolNode", "name": "x"},
{"type": "ConstantNode", "value": "2", "valueType": "number"},
],
},
}
evaluator = build_evaluator(
expressions=exprs,
inputs=["x"],
target=["low", "high"],
include_source=True,
)
assert evaluator({"x": 10}) == {"low": 8, "high": 12}
```
The source string includes the import preamble needed to re-execute it in an environment where `mathjs_to_func` is installed:
```python
namespace = {}
exec(evaluator.__mathjs_source__, namespace)
assert namespace["_compiled"]({"x": 10}) == evaluator({"x": 10})
```
### Supported math.js nodes
| Node | Notes |
|-------------------------|-------|
| `ConstantNode` | numeric (`number`), string, boolean, or `null` literals |
| `SymbolNode` | inputs, expression references, and common built-in constants; identifiers must be alphanumeric/underscore, starting with a letter/underscore |
| `OperatorNode` | `add`, `subtract`, `multiply`, `divide`, `pow`, `mod`, unary `unaryPlus`, `unaryMinus`, `not`, `and`, `or`, `xor`, comparisons, and `nullish` |
| `FunctionNode` | Common math.js numeric/statistical helpers, including trig, logs, `format`, `clamp`, `hypot`, integer combinatorics, `variance`, `std`, `mode`, `ifnull`, and operator aliases such as `add(a, b)` |
| `ParenthesisNode` | forwards to the wrapped expression |
| `ArrayNode` | materialised to Python lists/NumPy arrays |
| `AccessorNode`/`IndexNode` | read-only indexing with math.js 1-based indices translated to Python 0-based indices |
| `RangeNode` | materialised to inclusive NumPy ranges with optional non-zero step |
| `ObjectNode` | materialised to Python dict literals with string keys |
| `ConditionalNode` | lazy scalar ternary evaluation, vectorised NumPy `where` for arrays |
| `RelationalNode` | chained comparisons like `10 < x <= 50`, with scalar short-circuiting |
Unknown node types, invalid identifiers, or disallowed functions raise `InvalidNodeError` during compilation.
See [docs/compatibility.md](docs/compatibility.md) for the fuller math.js compatibility matrix and known gaps.
### Error handling
- `ExpressionError`: base class for configuration mistakes.
- `MissingTargetError`: requested target id does not exist.
- `UnknownIdentifierError`: an expression references a symbol that is neither an input nor another expression.
- `CircularDependencyError`: dependency graph contains a cycle.
- `InvalidNodeError`: AST contains unsupported structures or invalid literals.
- `InputValidationError`: the compiled function received inputs that are missing, unexpected, or not a mapping.
- `RuntimeEvaluationError`: a compiled expression failed at runtime; the original exception is preserved as `__cause__`.
All exceptions provide enough context (`expression` name, offending identifier, cycle list, etc.) to surface descriptive UI errors.
## Parsing math.js JSON
With the extra installed you can turn serialized math.js nodes into evaluator-ready mappings:
```python
from mathjs_to_func import build_evaluator
from mathjs_to_func.parse import parse
expression = parse(
"""{
"type": "OperatorNode",
"fn": "add",
"args": [
{"type": "SymbolNode", "name": "x"},
{"type": "ConstantNode", "value": "2", "valueType": "number"}
]
}"""
)
evaluator = build_evaluator(
expressions={"total": expression},
inputs=["x"],
target="total",
)
result = evaluator({"x": 40}) # -> 42
```
For complete `{expressions, inputs, target}` envelopes, use `parse_payload`:
```python
from mathjs_to_func import build_evaluator
from mathjs_to_func.parse import parse_payload
payload = parse_payload(serialized_payload)
evaluator = build_evaluator(payload=payload)
```
The parser also exposes Pydantic models such as `ConstantNode`, `SymbolNode`, and `OperatorNode` for typed payload construction. math.js replacer values such as `Complex`, `Unit`, `BigNumber`, and `Fraction` are rejected with explicit unsupported-value errors until those runtime types are implemented.
All examples below assume commands are wrapped with `uv run ...` to execute inside the managed environment.
## CLI
Compile a payload file and inspect the generated Python source without writing a script:
```bash
uv run python -m mathjs_to_func compile payload.json --target z --emit-source
```
Without `--emit-source`, the command validates the payload and prints metadata JSON containing the target, required inputs, and evaluation order. Use `-` as the payload path to read JSON from stdin.
## JSON Schema
Export JSON Schema for frontend validation of serialized math.js payloads:
```bash
uv run python -m mathjs_to_func schema --output dist/mathjs-to-func.schema.json
```
The default schema covers a complete evaluator payload (`expressions`, `inputs`, and `target`). Use `--kind expression` to export the schema for a single math.js expression tree.
## Implementation Notes
1. **AST translation** – `MathJsAstBuilder` walks the math.js JSON and emits Python `ast.AST` nodes. Identifiers are validated via a strict regex, and the generated runtime reserves the `__mj_` prefix for internal names.
2. **Dependency graph** – A topological sorter (`graphlib.TopologicalSorter`) runs over expression references to produce a safe evaluation order while catching cycles and missing references upfront.
3. **Code generation** – The generated function validates the provided scope, binds required inputs to local variables, evaluates expressions in order, and returns the target. Intermediate values are stored as local variables named after their expression id.
4. **Execution sandbox** – The compiled module is executed with a tightly scoped globals dictionary: helper math functions and a few safe built-ins only. There is no ambient `__builtins__` exposure.
5. **Helper functions** – math.js functions map onto small Python helpers for arithmetic, comparison, logical, nullish, formatting, and statistics behavior. Equality and ordering default to math.js-style tolerances for numeric round-off, configurable per evaluator with `EvalConfig`, `{"epsilon": ...}`, or `{"comparison": "mathjs" | "numpy" | "strict"}` for explicit comparison semantics.
### Introspection
Compiled evaluators expose `__mathjs_inputs_referenced_per_target__` alongside the existing source, target, input, and evaluation-order metadata. The public helpers `to_string(payload)`, `to_tex(payload)`, `to_dot(payload)`, `to_mermaid(payload)`, and `inputs_referenced_per_target(payload)` can be used before compilation to build UI labels, LaTeX tooltips, and dependency graph views.
### Cache Notes
`compile_cache=True` now uses a structural key rather than serializing through JSON. This avoids JSON round-trips for deep trees and lets hashable non-JSON constants participate in cache keys. The cache remains opt-in and process-local; tune it with `compile_cache_maxsize`.
## Testing
Run the full suite with:
```bash
uv run pytest
```
Run the benchmark suite locally with:
```bash
npm ci --prefix bench/js
uv run python -m bench
```
CI runs `uv run python -m bench --check` as a relative perf regression gate. The benchmark compares reusable `build_evaluator` call performance with Python `eval`, `simpleeval`, and a Node math.js parse → JSON round-trip → compile path across scalar arithmetic, conditional, helper-heavy, and NumPy payloads.
Run mutation testing with:
```bash
uv run mutmut run
uv run mutmut results
```
The GitHub mutation workflow runs on source and test changes, records the full mutmut result set, and emits a warning when any mutants survive.
The tests cover operator translation, helper semantics, dependency validation, error conditions, numpy-friendly behaviour, and public API ergonomics.
## Project Structure
```
src/mathjs_to_func/
├── __init__.py # build_evaluator public API and export list
├── ast_builder.py # math.js JSON → Python AST translation
├── compiler.py # dependency graph, code generation, compilation
├── errors.py # structured exception hierarchy
├── helpers.py # runtime helpers for math.js-compatible functions/operators
└── py.typed # PEP 561 marker for type-aware consumers
```
Additional documentation lives in `docs/api_design.md`, outlining the initial design considerations.
## Limitations & Future Work
- Only a subset of math.js functions/operators are implemented today; see the compatibility matrix for specifics.
- Units, user-defined functions, and incremental recomputation are intentionally out of scope for this milestone.
- Arrays are handled via NumPy; if you need bigints, complex numbers, or matrices, the helper layer will require extension.
Contributions and bug reports are welcome!