eqtheory 0.1.0__tar.gz

eqtheory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oliver Sick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eqtheory-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: eqtheory
+Version: 0.1.0
+Summary: Equational theories over magmas: term rewriting with a Knuth-Bendix order, proof-producing e-graphs, goal-directed superposition, finite and infinite countermodels, Lean 4 certificates.
+Author: Oliver Sick
+License: MIT
+Keywords: equational theories,magma,term rewriting,e-graph,superposition,Lean 4,SAT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: viz
+Requires-Dist: graphviz>=0.20; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# eqtheory
+
+A Python library for **equational theories over magmas**: given two
+equations in one binary operation `◇`, decide whether the first implies
+the second — and hand back a **Lean 4 certificate** either way.
+
+* term rewriting with a ground **Knuth–Bendix order**, one-way matching,
+  unification,
+* a proof-producing **e-graph** (congruence closure with a proof forest,
+  shortest shared explanations) and **equality saturation**,
+* **ordered completion** and **goal-directed superposition** with
+  replayed proof chains, interreduction and node budgets,
+* **finite countermodels**: symbolic linear families, structured tables,
+  a complete propagating cell search and a **CDCL** SAT search with
+  symmetry breaking (exhaustion verdicts are proofs),
+* **infinite countermodels on ℕ** for *Austin pairs* (true in every
+  finite magma, false in general),
+* **Lean 4 certificates** for every answer, in the shapes accepted by the
+  SAIR Stage-2 judge, with an optional compile check,
+* an optional, hygienic **LLM stage** with a configurable prompt,
+* a **CLI** with e-graph and proof **visualisation** (SVG/PNG/DOT).
+
+The algorithms are those of the SAIR Stage-2 solver (800/800 practice,
+see the paper in [osick/SAIR-callenges](https://github.com/osick/SAIR-callenges/tree/main/challenge_02/docs/paper)),
+re-packaged with a clean API. Pure Python 3.11+,
+no required dependencies.
+
+```bash
+pip install -e .            # from this directory
+pip install -e ".[viz,dev]" # graphviz bindings, pytest
+```
+
+## Quick start
+
+```python
+from eqtheory import Problem, solve
+
+p = Problem.parse("x = y ◇ (x ◇ y)", "x = (x ◇ y) ◇ x")
+ans = solve(p)
+print(ans.verdict, ans.stage)   # "true" / "false", which engine decided
+print(ans.code)                 # the Lean 4 certificate
+```
+
+Each engine is a plain function:
+
+```python
+from eqtheory import prove_by_superposition, find_countermodel, residue_affine_countermodel, prove_goal
+from eqtheory.lean import certs
+
+pr = prove_by_superposition(p.hypothesis, p.goal)       # lemma + instantiation + derived set
+cm = find_countermodel(p.hypothesis, p.goal, time_budget=60)   # Countermodel(n, table) or None
+nm = residue_affine_countermodel(p.hypothesis, p.goal)  # ℕ model for Austin pairs
+eg, l, r = prove_goal(p.hypothesis, p.goal)             # e-graph with the goal sides merged
+lemmas, chain = eg.explain(l, r)                        # shared proof, replayable
+eg.render("egraph.svg", highlight=(l, r))               # picture
+```
+
+## Command line
+
+```bash
+eqtheory solve "x = y ◇ (x ◇ y)" "x = (x ◇ y) ◇ x"                # full ladder, prints certificate
+eqtheory solve --lean --json ...                                # certificate compiled with Lean
+eqtheory prove ...                                              # superposition only
+eqtheory model --infinite --cert ...                            # countermodels, finite then ℕ
+eqtheory egraph --render egraph.svg --lemmas ...                # saturate and draw the e-graph
+eqtheory viz-proof --out proof.dot ...                          # the extracted proof as a graph
+eqtheory cert --table "[[0,1],[1,0]]" ...                       # wrap a table as a certificate
+```
+
+`--lean` needs `EQTHEORY_LEAN_BIN` (a Lean 4.33 binary) and
+`EQTHEORY_JUDGE_ROOT` (a built checkout of the Stage-2 judge library) or
+`EQTHEORY_LEAN_PATH`. `--llm` needs `OPENROUTER_API_KEY`.
+
+## Documentation
+
+* [User guide](docs/guide.md) — the pipeline, budgets, composing your own ladder
+* [Mathematical background](docs/background.md) — the theory behind each engine, with references
+* [Certificates](docs/certificates.md) — the Lean shapes and the proof-policy lessons
+* [API overview](docs/api.md)
+* [Limitations](docs/limitations.md) — theoretical and pragmatic
+* [Releasing](docs/releasing.md) — moving to its own repository, CI, tags, PyPI
+* `examples/single_file_solver.py` — a complete solver in 60 lines
+* `artifacts/` — sample renderings and benchmark reports
+
+## Status
+
+Version 0.1.0 (2026-09-01). Tests: `python -m pytest` (70 tests; the Lean
+end-to-end test is skipped unless Lean is configured). Benchmark (2026-09-01, 200-problem Stage-2 stress set, every certificate
+compiled with Lean, LLM never needed): **200/200 correct** — see
+`artifacts/bench-stress-2026-09-01/REPORT.md`.
+
+## Limitations (short form)
+
+Implication between magma laws is undecidable; every engine is budgeted,
+so "no answer" is not a verdict. Finite search is complete per size but
+cannot see infinite-only countermodels beyond the ℕ residue-class family;
+table certificates stop at Fin 10 (affine models go further); `grind`
+certificates are Lean-version-sensitive; the compile check is not the
+competition judge; the LLM stage adds hygiene, not reach. Details and
+measurements: [docs/limitations.md](docs/limitations.md).
+
+License: MIT.

eqtheory-0.1.0/README.md

@@ -0,0 +1,102 @@
+# eqtheory
+
+A Python library for **equational theories over magmas**: given two
+equations in one binary operation `◇`, decide whether the first implies
+the second — and hand back a **Lean 4 certificate** either way.
+
+* term rewriting with a ground **Knuth–Bendix order**, one-way matching,
+  unification,
+* a proof-producing **e-graph** (congruence closure with a proof forest,
+  shortest shared explanations) and **equality saturation**,
+* **ordered completion** and **goal-directed superposition** with
+  replayed proof chains, interreduction and node budgets,
+* **finite countermodels**: symbolic linear families, structured tables,
+  a complete propagating cell search and a **CDCL** SAT search with
+  symmetry breaking (exhaustion verdicts are proofs),
+* **infinite countermodels on ℕ** for *Austin pairs* (true in every
+  finite magma, false in general),
+* **Lean 4 certificates** for every answer, in the shapes accepted by the
+  SAIR Stage-2 judge, with an optional compile check,
+* an optional, hygienic **LLM stage** with a configurable prompt,
+* a **CLI** with e-graph and proof **visualisation** (SVG/PNG/DOT).
+
+The algorithms are those of the SAIR Stage-2 solver (800/800 practice,
+see the paper in [osick/SAIR-callenges](https://github.com/osick/SAIR-callenges/tree/main/challenge_02/docs/paper)),
+re-packaged with a clean API. Pure Python 3.11+,
+no required dependencies.
+
+```bash
+pip install -e .            # from this directory
+pip install -e ".[viz,dev]" # graphviz bindings, pytest
+```
+
+## Quick start
+
+```python
+from eqtheory import Problem, solve
+
+p = Problem.parse("x = y ◇ (x ◇ y)", "x = (x ◇ y) ◇ x")
+ans = solve(p)
+print(ans.verdict, ans.stage)   # "true" / "false", which engine decided
+print(ans.code)                 # the Lean 4 certificate
+```
+
+Each engine is a plain function:
+
+```python
+from eqtheory import prove_by_superposition, find_countermodel, residue_affine_countermodel, prove_goal
+from eqtheory.lean import certs
+
+pr = prove_by_superposition(p.hypothesis, p.goal)       # lemma + instantiation + derived set
+cm = find_countermodel(p.hypothesis, p.goal, time_budget=60)   # Countermodel(n, table) or None
+nm = residue_affine_countermodel(p.hypothesis, p.goal)  # ℕ model for Austin pairs
+eg, l, r = prove_goal(p.hypothesis, p.goal)             # e-graph with the goal sides merged
+lemmas, chain = eg.explain(l, r)                        # shared proof, replayable
+eg.render("egraph.svg", highlight=(l, r))               # picture
+```
+
+## Command line
+
+```bash
+eqtheory solve "x = y ◇ (x ◇ y)" "x = (x ◇ y) ◇ x"                # full ladder, prints certificate
+eqtheory solve --lean --json ...                                # certificate compiled with Lean
+eqtheory prove ...                                              # superposition only
+eqtheory model --infinite --cert ...                            # countermodels, finite then ℕ
+eqtheory egraph --render egraph.svg --lemmas ...                # saturate and draw the e-graph
+eqtheory viz-proof --out proof.dot ...                          # the extracted proof as a graph
+eqtheory cert --table "[[0,1],[1,0]]" ...                       # wrap a table as a certificate
+```
+
+`--lean` needs `EQTHEORY_LEAN_BIN` (a Lean 4.33 binary) and
+`EQTHEORY_JUDGE_ROOT` (a built checkout of the Stage-2 judge library) or
+`EQTHEORY_LEAN_PATH`. `--llm` needs `OPENROUTER_API_KEY`.
+
+## Documentation
+
+* [User guide](docs/guide.md) — the pipeline, budgets, composing your own ladder
+* [Mathematical background](docs/background.md) — the theory behind each engine, with references
+* [Certificates](docs/certificates.md) — the Lean shapes and the proof-policy lessons
+* [API overview](docs/api.md)
+* [Limitations](docs/limitations.md) — theoretical and pragmatic
+* [Releasing](docs/releasing.md) — moving to its own repository, CI, tags, PyPI
+* `examples/single_file_solver.py` — a complete solver in 60 lines
+* `artifacts/` — sample renderings and benchmark reports
+
+## Status
+
+Version 0.1.0 (2026-09-01). Tests: `python -m pytest` (70 tests; the Lean
+end-to-end test is skipped unless Lean is configured). Benchmark (2026-09-01, 200-problem Stage-2 stress set, every certificate
+compiled with Lean, LLM never needed): **200/200 correct** — see
+`artifacts/bench-stress-2026-09-01/REPORT.md`.
+
+## Limitations (short form)
+
+Implication between magma laws is undecidable; every engine is budgeted,
+so "no answer" is not a verdict. Finite search is complete per size but
+cannot see infinite-only countermodels beyond the ℕ residue-class family;
+table certificates stop at Fin 10 (affine models go further); `grind`
+certificates are Lean-version-sensitive; the compile check is not the
+competition judge; the LLM stage adds hygiene, not reach. Details and
+measurements: [docs/limitations.md](docs/limitations.md).
+
+License: MIT.

eqtheory-0.1.0/eqtheory/__init__.py

@@ -0,0 +1,31 @@
+"""eqtheory — equational theories over magmas.
+
+Term rewriting with a Knuth–Bendix order, proof-producing e-graph
+saturation, goal-directed superposition, finite and infinite countermodel
+search, and Lean 4 certificate generation. The algorithms of the SAIR
+Stage-2 solver (2026) as a library; no lookup tables, no stored proofs —
+everything is derived from the two equations of a problem at runtime.
+"""
+from .terms import (  # noqa: F401
+    Equation, Problem, Term, OP,
+    parse_term, render_term, parse_equation, normalize,
+    term_vars, term_leaves, positions, subterm, replace_at,
+    match, unify, substitute, rename,
+    kbo_greater, holds, evaluate,
+)
+
+__version__ = "0.1.0"
+
+from .solve import solve, Answer, Config, Trace  # noqa: E402,F401
+from .completion import derive_lemmas, prove_by_superposition, Budget  # noqa: E402,F401
+from .egraph import EGraph, saturate, prove_goal, prove_singleton  # noqa: E402,F401
+from .models import find_countermodel, residue_affine_countermodel, Countermodel, NatResidueModel  # noqa: E402,F401
+
+__all__ = [
+    "Equation", "Problem", "Term", "OP", "parse_term", "render_term", "parse_equation", "normalize",
+    "term_vars", "term_leaves", "positions", "subterm", "replace_at", "match", "unify", "substitute", "rename",
+    "kbo_greater", "holds", "evaluate",
+    "solve", "Answer", "Config", "Trace", "derive_lemmas", "prove_by_superposition", "Budget",
+    "EGraph", "saturate", "prove_goal", "prove_singleton",
+    "find_countermodel", "residue_affine_countermodel", "Countermodel", "NatResidueModel", "__version__",
+]

eqtheory-0.1.0/eqtheory/cli.py

@@ -0,0 +1,192 @@
+"""Command line: ``eqtheory solve|egraph|model|cert|prove|viz-proof``."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+
+from . import __version__, completion, egraph, llm as llm_mod, viz
+from .solve import solve as run_solve, Config, Trace
+from .lean import certs, check as lean_check
+from .models import finite, infinite
+from .terms import Problem
+
+
+def _problem(a) -> Problem:
+    return Problem.parse(a.hypothesis, a.goal)
+
+
+def _judge(a):
+    if not getattr(a, "lean", False):
+        return None
+    cfg = lean_check.configure(timeout=a.lean_timeout)
+    if cfg is None:
+        sys.exit("Lean not configured: set EQTHEORY_LEAN_BIN and EQTHEORY_JUDGE_ROOT (or EQTHEORY_LEAN_PATH)")
+    pr = _problem(a)
+    return lean_check.make_judge(pr.hypothesis, pr.goal, cfg)
+
+
+def cmd_solve(a):
+    pr = _problem(a)
+    cfg = Config(model_budget=a.model_budget, superposition_budget=a.superposition_budget,
+                           eqsat_budget=a.eqsat_budget, infinite_budget=a.infinite_budget, llm_rounds=a.llm_rounds)
+    complete = None
+    if a.llm:
+        complete = llm_mod.OpenRouterClient(model=a.llm_model, seed=a.llm_seed, reasoning_effort=a.llm_effort)
+    tr = Trace()
+    t0 = time.monotonic()
+    ans = run_solve(pr, cfg, judge=_judge(a), complete=complete, trace=tr)
+    out = {"hypothesis": pr.hypothesis.text, "goal": pr.goal.text, "seconds": round(time.monotonic() - t0, 2),
+           "verdict": ans.verdict if ans else None, "stage": ans.stage if ans else None,
+           "verified": ans.verified if ans else None,
+           "facts": {"exhausted": tr.facts.exhausted, "searched": tr.facts.searched},
+           "trace": tr.steps}
+    if a.json:
+        out["code"] = ans.code if ans else None
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+        return
+    print(f"{pr.hypothesis.text}  ⇒  {pr.goal.text}")
+    for stage, sec, note in tr.steps:
+        print(f"  {stage:24s} {sec:8.2f}s  {note}")
+    if ans is None:
+        print("no answer")
+        return
+    print(f"verdict: {ans.verdict}  (stage {ans.stage}{'' if ans.verified else ', UNVERIFIED'})")
+    if a.out:
+        open(a.out, "w", encoding="utf-8").write(ans.code)
+        print(f"certificate written to {a.out}")
+    else:
+        print(ans.code)
+
+
+def cmd_egraph(a):
+    pr = _problem(a)
+    lemmas = completion.derive_lemmas(pr.hypothesis) if a.lemmas else []
+    eg, l, r, ok = egraph.saturate(pr.hypothesis, pr.goal.variables, (pr.goal.lhs, pr.goal.rhs), lemmas=lemmas,
+                                   time_budget=a.budget, inst_cap=a.inst_cap, max_rounds=a.rounds)
+    n_classes = len(eg.classes())
+    print(f"e-graph: {len(eg.nodes)} nodes, {n_classes} classes, goal sides {'merged' if ok else 'NOT merged'}")
+    if a.render:
+        kind = viz.render_egraph(eg, a.render, highlight=(l, r), proof_pairs=((l, r),) if ok else (),
+                                 max_classes=a.max_classes)
+        print(f"rendered ({kind}) → {a.render}")
+    if a.dot:
+        open(a.dot, "w", encoding="utf-8").write(viz.egraph_to_dot(eg, highlight=(l, r), max_classes=a.max_classes))
+        print(f"dot → {a.dot}")
+
+
+def cmd_model(a):
+    pr = _problem(a)
+    facts = finite.SearchFacts()
+    cm = finite.find_countermodel(pr.hypothesis, pr.goal, time_budget=a.budget, max_n=a.max_n, facts=facts)
+    if cm is not None:
+        print(f"countermodel on Fin {cm.n}:")
+        for row in cm.table:
+            print("  " + " ".join(str(v) for v in row))
+        aff = cm.affine_form()
+        if aff:
+            print(f"  affine: (a·i + b·j + c) mod n with (a, b, c) = {aff}")
+        if a.cert:
+            print(certs.false_code(cm.n, cm.table))
+        return
+    print(f"no finite countermodel found; sizes proven empty: {facts.exhausted}, swept: {facts.searched}")
+    if a.infinite:
+        m = infinite.residue_affine_countermodel(pr.hypothesis, pr.goal, time_budget=a.budget)
+        if m is None:
+            print("no residue-class affine model on ℕ")
+            return
+        print(f"ℕ model: m={m.m} A={m.A} B={m.B} C={m.C} witness={m.witness}")
+        if a.cert:
+            print(certs.false_nat_residue_code(pr.hypothesis, m.m, m.A, m.B, m.C, m.witness))
+
+
+def cmd_prove(a):
+    pr = _problem(a)
+    t0 = time.monotonic()
+    proof = completion.prove_by_superposition(pr.hypothesis, pr.goal, deadline=time.monotonic() + a.budget)
+    if proof is None:
+        print(f"no superposition proof within {a.budget}s")
+        return
+    print(f"proved by {proof.lemma['name']} in {time.monotonic() - t0:.1f}s "
+          f"({len(proof.derived)} lemmas derived)")
+    code = certs.superposition_code(pr.hypothesis, pr.goal, proof)
+    print(code)
+
+
+def cmd_cert(a):
+    pr = _problem(a)
+    if a.table:
+        table = json.loads(a.table)
+        if not finite.is_countermodel(pr.hypothesis, pr.goal, len(table), table):
+            sys.exit("the table is not a countermodel of this problem")
+        print(certs.false_code(len(table), table))
+    elif a.proof:
+        print(certs.true_code(open(a.proof, encoding="utf-8").read()))
+    else:
+        sys.exit("give --table or --proof")
+
+
+def cmd_viz_proof(a):
+    pr = _problem(a)
+    res = egraph.prove_goal(pr.hypothesis, pr.goal, time_budget=a.budget)
+    if res is None:
+        sys.exit("saturation did not connect the goal sides")
+    eg, l, r = res
+    lemmas, chain = eg.explain(l, r)
+    dot = viz.chain_to_dot(lemmas, chain, title=f"{pr.hypothesis.text} ⇒ {pr.goal.text}")
+    open(a.out, "w", encoding="utf-8").write(dot)
+    print(f"proof graph (dot) → {a.out}; {len(lemmas)} shared lemmas, chain length {len(chain)}")
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="eqtheory", description="equational theories over magmas")
+    p.add_argument("--version", action="version", version=f"eqtheory {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def common(sp, lean=False):
+        sp.add_argument("hypothesis", help='e.g. "x = y ◇ (x ◇ y)"')
+        sp.add_argument("goal")
+        if lean:
+            sp.add_argument("--lean", action="store_true", help="check certificates with Lean (EQTHEORY_* env)")
+            sp.add_argument("--lean-timeout", type=float, default=300.0)
+
+    s = sub.add_parser("solve", help="run the full ladder"); common(s, lean=True)
+    s.add_argument("--json", action="store_true"); s.add_argument("--out", help="write the certificate here")
+    s.add_argument("--model-budget", type=float, default=60.0); s.add_argument("--superposition-budget", type=float, default=300.0)
+    s.add_argument("--eqsat-budget", type=float, default=25.0); s.add_argument("--infinite-budget", type=float, default=20.0)
+    s.add_argument("--llm", action="store_true", help="add an LLM round (OPENROUTER_API_KEY)")
+    s.add_argument("--llm-model", default="openai/gpt-oss-120b"); s.add_argument("--llm-seed", type=int, default=0)
+    s.add_argument("--llm-effort", default="low"); s.add_argument("--llm-rounds", type=int, default=4)
+    s.set_defaults(fn=cmd_solve)
+
+    s = sub.add_parser("egraph", help="saturate and render the e-graph"); common(s)
+    s.add_argument("--render", metavar="FILE", help="image output (.svg/.png/.pdf; graphviz optional)")
+    s.add_argument("--dot", metavar="FILE"); s.add_argument("--lemmas", action="store_true")
+    s.add_argument("--budget", type=float, default=10.0); s.add_argument("--inst-cap", type=int, default=20_000)
+    s.add_argument("--rounds", type=int, default=8); s.add_argument("--max-classes", type=int, default=200)
+    s.set_defaults(fn=cmd_egraph)
+
+    s = sub.add_parser("model", help="search countermodels"); common(s)
+    s.add_argument("--budget", type=float, default=60.0); s.add_argument("--max-n", type=int, default=finite.MAX_TABLE_N)
+    s.add_argument("--infinite", action="store_true", help="also try the ℕ residue-class family")
+    s.add_argument("--cert", action="store_true", help="print the Lean certificate")
+    s.set_defaults(fn=cmd_model)
+
+    s = sub.add_parser("prove", help="goal-directed superposition"); common(s)
+    s.add_argument("--budget", type=float, default=300.0); s.set_defaults(fn=cmd_prove)
+
+    s = sub.add_parser("cert", help="wrap a table or a tactic body as a certificate"); common(s)
+    s.add_argument("--table", help="JSON table"); s.add_argument("--proof", help="file with a tactic body")
+    s.set_defaults(fn=cmd_cert)
+
+    s = sub.add_parser("viz-proof", help="render an e-graph proof as a dot graph"); common(s)
+    s.add_argument("--out", required=True); s.add_argument("--budget", type=float, default=10.0)
+    s.set_defaults(fn=cmd_viz_proof)
+
+    a = p.parse_args(argv)
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()