Metadata-Version: 2.4
Name: elegua
Version: 0.2.0
Summary: Domain-agnostic multi-tier test harness for validating mathematical equivalence
Project-URL: Homepage, https://github.com/sashakile/elegua
Project-URL: Repository, https://github.com/sashakile/elegua
Author-email: sashakile <saxa.kile@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: computer-algebra,oracle,testing,verification,wolfram
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: hypothesis>=6.0
Requires-Dist: numpy>=1.22
Requires-Dist: pydantic>=2.0
Provides-Extra: sympy
Requires-Dist: sympy>=1.13; extra == 'sympy'
Provides-Extra: wolfram
Requires-Dist: flask>=3.0; extra == 'wolfram'
Requires-Dist: wolframclient>=1.1; extra == 'wolfram'
Description-Content-Type: text/markdown

# 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](https://www.python.org/downloads/)
- **uv** — `curl -LsSf https://astral.sh/uv/install.sh | sh` ([docs](https://docs.astral.sh/uv/))

**Install and run one comparison:**

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

Then run a quick comparison:

```python
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](https://sashakile.github.io/elegua/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](https://sashakile.github.io/elegua/guide/adapters/) 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.

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

> [!WARNING]
> All code in this repository is generated by AI. Use at your own caution. It was built under strict engineering practices but is not warranted to be absolutely correct. The only way to validate its correctness is to use it and identify failures. This repository is in an experimental phase and was meant to explore how to use AI to develop scientific software. Feel free to open issues; pull requests are momentarily closed until I (or industry, communities) figure out a way to manage them.

## License

MIT
