Eleguá

Domain-agnostic, multi-tier test harness for validating mathematical equivalence across symbolic computing systems.

The problem

When you port a symbolic math library to a new language, how do you prove the new implementation produces the same results as the original? Manual spot-checks don't scale — you need automated, layer-by-layer comparison that catches everything from bitwise differences to deep semantic mismatches.

What Eleguá does

Eleguá orchestrates validation tasks across multiple implementations of the same mathematical system. It runs the same symbolic action on a high-fidelity Oracle (ground truth) and one or more Implementations Under Test, then compares results through a 4-layer pipeline that cascades from fast structural checks to deeper semantic and invariant-based comparison.

TOML fixture → EleguaTask → Adapter.execute() → ValidationToken → Comparison Pipeline → pass/fail

Choose your path

1. Evaluate Eleguá

Run your first comparison using the built-in stubs in under five minutes.

Minimal prerequisites:

• Python 3.11+ — python.org/downloads
• uv — curl -LsSf https://astral.sh/uv/install.sh | sh (docs)

Install and run one comparison:

git clone https://github.com/sashakile/elegua.git  # or git@github.com:sashakile/elegua.git
cd elegua
uv sync

Then run a quick comparison:

from elegua.adapter import WolframAdapter
from elegua.comparison import compare_pipeline
from elegua.task import EleguaTask

task = EleguaTask(action="Echo", payload={"expr": "x + y"})
a = WolframAdapter().execute(task)
b = WolframAdapter().execute(task)
result = compare_pipeline(a, b)
print(result.layer, result.layer_name, result.status.value)
# => 1 identity ok

See the Getting Started guide for the full tutorial.

2. Build an adapter

To validate your own symbolic engine, you need to connect it to the harness. Eleguá uses a simple Adapter interface to dispatch tasks and receive validation tokens.

Read Writing an adapter in the documentation to learn how to plug your system into the 4-layer comparison pipeline.

3. Contribute

If you plan to work on the Eleguá repository itself, you'll need the full contributor environment.

just setup      # install deps, sync vale, configure hooks
just check      # run all pre-commit checks
just fix        # auto-fix lint and format issues
just test       # run tests (pass args: just test -v -k blob)
just cov        # run tests with coverage report
just ci         # full local CI: check + test

Git hooks (installed by just setup): pre-commit runs ruff, pyright, typos, and vale; pre-push runs pytest.

CI runs on push and PR to main: lint, typecheck, typos, vale, and test matrix across Python 3.11–3.13.

Experimental Status

License

MIT