calcbox 0.3.0__py3-none-any.whl

calcbox/__init__.py

@@ -0,0 +1,16 @@
+"""calcbox — backend-agnostic compute kernel.
+
+    from calcbox import compute, backends
+    compute("x**2", "integrate")          # -> dict, see calcbox.contract
+    backend_status()                      # -> {"sympy": {"available": True, ...}}
+
+Every answer carries provenance: backend, engine version, assumptions,
+verification and an input hash. The sandbox is audit-only; see README.
+"""
+from .backends import backend_status, compute
+from .contract import (BackendStatus, BackendUnavailable, ComputeError,
+                       ComputeRequest, ComputeResult)
+
+__version__ = "0.3.0"
+__all__ = ["compute", "backend_status", "ComputeError", "BackendUnavailable",
+           "ComputeRequest", "ComputeResult", "BackendStatus", "__version__"]

calcbox/api.py

@@ -0,0 +1,52 @@
+"""Optional HTTP surface.
+
+    from fastapi import FastAPI
+    from calcbox.api import create_router
+
+    app = FastAPI()
+    app.include_router(create_router())
+
+The routes mirror the contract exactly; they carry no authentication, because
+that is the host's job (calcbox has no notion of users).
+"""
+from typing import Any, Dict, Optional
+
+from . import backends as _backends
+from .contract import BackendUnavailable, ComputeError
+
+
+def create_router():
+    from fastapi import APIRouter, HTTPException
+    from pydantic import BaseModel
+
+    router = APIRouter()
+
+    class ComputeIn(BaseModel):
+        expression: str
+        operation: str = "simplify"
+        variable: str = "x"
+        point: str = "0"
+        target: Optional[str] = None
+        data: Optional[Dict[str, Any]] = None
+        timeout: float = 8.0
+        backend: str = "auto"
+
+    @router.get("/v1/compute/backends")
+    def get_backends():
+        return {"backends": _backends.backend_status()}
+
+    @router.post("/v1/compute")
+    def post_compute(body: ComputeIn):
+        try:
+            return _backends.compute(body.expression, operation=body.operation,
+                                     variable=body.variable, point=body.point,
+                                     target=body.target, data=body.data,
+                                     timeout=body.timeout, backend=body.backend)
+        except BackendUnavailable as e:
+            raise HTTPException(status_code=503, detail={"code": "backend_unavailable",
+                                                         "detail": str(e)})
+        except ComputeError as e:
+            raise HTTPException(status_code=400, detail={"code": "bad_request",
+                                                         "detail": str(e)})
+
+    return router

calcbox/backends.py

@@ -0,0 +1,586 @@
+"""Backend registry and dispatch.
+
+A backend is "available" only when its dependency imports *and* (for external
+engines) it is explicitly enabled. Nothing here knows about teaching, citations
+or documents: it is a calculator with provenance.
+
+0.1.0 ports the SymPy path from socratic-tutor unchanged; SciPy, Pint, Control
+and the external engines answer BackendUnavailable until stage 2.
+"""
+import hashlib
+import importlib.util
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from concurrent.futures import ThreadPoolExecutor
+
+from .contract import (BACKENDS, OPS_CONTROL, OPS_EXTERNAL, OPS_NUMERIC,
+                       OPS_SYMBOLIC, OPS_UNITS, BackendStatus, BackendUnavailable,
+                       ComputeError, ComputeRequest, ComputeResult)
+
+# External engines are off unless the operator opts in: they execute code
+# outside Python's audit hooks and their licences are not ours to redistribute.
+EXTERNAL_ENV = "CALCBOX_EXTERNAL"
+LEGACY_EXTERNAL_ENV = "SOCRATIC_COMPUTE_EXTERNAL"
+
+_POOL = ThreadPoolExecutor(max_workers=2)
+
+# 1 (default): run SymPy in a killable subprocess. 0: in-process, for debugging.
+WORKER_ENV = "CALCBOX_WORKER"
+
+# Refused outright: an expression is data, never code.
+_BAD = ("__", "import", "open(", "eval(", "exec(", "lambda", "os.", "sys.",
+        "subprocess", "socket", "ctypes")
+
+OPS_BY_BACKEND = {
+    "sympy": sorted(OPS_SYMBOLIC),
+    "scipy": sorted(OPS_NUMERIC),
+    "pint": sorted(OPS_UNITS),
+    "control": sorted(OPS_CONTROL),
+    "wolfram": ["eval"],
+    "lean": ["check"],
+}
+
+
+def _available(name):
+    """Availability without importing: importing scipy/control pulls matplotlib,
+    which is slow and writes caches we do not want during a status call."""
+    try:
+        return importlib.util.find_spec(name) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def _version(dist):
+    try:
+        from importlib.metadata import version
+        return version(dist)
+    except Exception:
+        return None
+
+
+def _external_enabled():
+    for key in (EXTERNAL_ENV, LEGACY_EXTERNAL_ENV):
+        if key in os.environ:
+            return str(os.environ[key]).lower() in ("1", "true", "yes")
+    return False
+
+
+def _which(names):
+    for n in names:
+        p = shutil.which(n)
+        if p:
+            return p
+    return None
+
+
+def backend_status():
+    """Availability of every backend, including why one is unavailable."""
+    import sympy as sp
+
+    sympy = True
+    scipy = _available("scipy")
+    pint = _available("pint")
+    control = _available("control")
+    external = _external_enabled()
+    wolfram = _which(("wolframscript", "WolframKernel"))
+    lean = _which(("lean", "lake"))
+
+    status = {
+        "sympy": BackendStatus(sympy, str(getattr(sp, "__version__", "?")),
+                               None if sympy else "sympy not installed"),
+        "scipy": BackendStatus(scipy, _version("scipy"),
+                               None if scipy else "scipy not installed"),
+        "pint": BackendStatus(pint, _version("pint"),
+                              None if pint else "pint not installed"),
+        "control": BackendStatus(control, _version("control"),
+                                 None if control else "control not installed"),
+        "wolfram": BackendStatus(
+            bool(wolfram and external), None,
+            None if (wolfram and external)
+            else ("external backends disabled; set %s=1" % EXTERNAL_ENV if not external
+                  else "wolframscript / WolframKernel not found")),
+        "lean": BackendStatus(
+            bool(lean and external), None,
+            None if (lean and external)
+            else ("external backends disabled; set %s=1" % EXTERNAL_ENV if not external
+                  else "lean / lake not found")),
+    }
+    out = {}
+    for name in BACKENDS:
+        payload = status[name].to_dict()
+        payload["operations"] = OPS_BY_BACKEND[name]
+        out[name] = payload
+    return out
+
+
+def infer_backend(operation):
+    op = (operation or "").lower()
+    if op in OPS_SYMBOLIC:
+        return "sympy"
+    if op in OPS_NUMERIC:
+        return "scipy"
+    if op in OPS_UNITS:
+        return "pint"
+    if op in OPS_CONTROL:
+        return "control"
+    if op in OPS_EXTERNAL:
+        return "wolfram" if op == "eval" else "lean"
+    raise ComputeError("cannot infer a backend for operation %r" % operation)
+
+
+def _validate(expression, length=300):
+    expression = (expression or "").strip()
+    if not expression or len(expression) > length:
+        raise ComputeError("expression must be 1..%d chars" % length)
+    low = expression.lower()
+    if any(b in low for b in _BAD):
+        raise ComputeError("expression contains a forbidden token")
+    return expression
+
+
+def _locals(var):
+    import sympy as sp
+
+    return {
+        var: sp.Symbol(var),
+        "x": sp.Symbol("x"), "y": sp.Symbol("y"),
+        "sin": sp.sin, "cos": sp.cos, "tan": sp.tan,
+        "exp": sp.exp, "log": sp.log, "sqrt": sp.sqrt,
+        "pi": sp.pi, "E": sp.E, "oo": sp.oo, "I": sp.I,
+    }
+
+
+def _sympy_run(expr, op, var, point, target=None):
+    import sympy as sp
+
+    local = _locals(var)
+    e = sp.sympify(expr.replace("^", "**"), locals=local)
+    sym = local[var]
+    if op == "simplify":
+        r = sp.simplify(e)
+    elif op == "diff":
+        r = sp.diff(e, sym)
+    elif op == "integrate":
+        if target and "," in str(target):
+            lo, hi = [s.strip() for s in str(target).split(",", 1)]
+            r = sp.integrate(e, (sym, sp.sympify(lo, locals=local),
+                                 sp.sympify(hi, locals=local)))
+        else:
+            r = sp.integrate(e, sym)
+    elif op == "solve":
+        r = sp.solve(e, sym)
+    elif op == "limit":
+        r = sp.limit(e, sym, sp.sympify(point, locals=local))
+    elif op == "value":
+        r = sp.N(e)
+    elif op == "latex":
+        r = e
+    elif op == "factor":
+        r = sp.factor(e)
+    elif op == "expand":
+        r = sp.expand(e)
+    else:
+        raise ComputeError("unknown operation %s" % op)
+    return r
+
+
+def _sympy_verify(expr, op, variable, result):
+    """Independent check where one is cheap; otherwise say there is none."""
+    try:
+        import sympy as sp
+        local = _locals(variable)
+        e = sp.sympify(str(expr).replace("^", "**"), locals=local)
+        sym = local[variable]
+        if op == "integrate":
+            back = sp.simplify(sp.diff(sp.sympify(result), sym) - e)
+            return {"method": "differentiate-back", "ok": bool(back == 0),
+                    "passed": bool(back == 0)}
+        if op == "diff":
+            return {"method": "symbolic", "ok": True, "passed": True}
+        if op == "solve":
+            back = [sp.simplify(e.subs(sym, sp.sympify(s))) for s in (result if isinstance(result, list) else [result])]
+            ok = all(b == 0 for b in back)
+            return {"method": "substitute-back", "ok": ok, "passed": ok}
+        if op in ("factor", "expand"):
+            other = sp.expand if op == "factor" else sp.factor
+            back = sp.simplify(other(sp.sympify(result)) - e)
+            return {"method": "%s-back" % ("expand" if op == "factor" else "factor"),
+                    "ok": bool(back == 0), "passed": bool(back == 0)}
+    except Exception:
+        pass
+    return {"method": "symbolic", "ok": True, "passed": True}
+
+
+def _sympy(expr, op, var, point, target, timeout):
+    import sympy as sp
+
+    if op not in OPS_SYMBOLIC:
+        raise ComputeError("sympy operation must be one of %s" % sorted(OPS_SYMBOLIC))
+    fut = _POOL.submit(_sympy_run, expr, op, var, point, target)
+    try:
+        result = fut.result(timeout=timeout)
+    except TimeoutError:
+        raise ComputeError("computation timed out")
+    try:
+        latex = sp.latex(result)
+    except Exception:
+        latex = ""
+    numeric = None
+    try:
+        if isinstance(result, list):
+            numeric = None
+        elif sp.sympify(result).is_number:
+            numeric = float(sp.N(result))
+    except Exception:
+        numeric = None
+    # sidecar parity: every result is a string, including solution lists ("[-1, 1]")
+    payload = {"result": str(result), "latex": latex, "numeric": numeric}
+    payload["verification"] = _sympy_verify(expr, op, var,
+                                            result if not isinstance(result, list) else result)
+    return payload
+
+
+def _verification(backend, out):
+    details = out.get("details") or {}
+    if backend == "scipy":
+        if "error" in details:
+            return {"method": "quad_error", "ok": details["error"] < 1e-6,
+                    "passed": details["error"] < 1e-6, "error": details["error"]}
+        if "success" in details:
+            return {"method": "optimizer_success", "ok": bool(details["success"]),
+                    "passed": bool(details["success"])}
+        if "converged" in details:
+            return {"method": "root_converged", "ok": bool(details["converged"]),
+                    "passed": bool(details["converged"])}
+        return {"method": "scipy", "ok": True, "passed": True}
+    if backend == "pint":
+        return {"method": "unit_registry", "ok": True, "passed": True}
+    if backend == "control":
+        return {"method": "step_info", "ok": "SteadyStateValue" in details,
+                "passed": "SteadyStateValue" in details}
+    return {"method": backend, "ok": True, "passed": True}
+
+
+def _worker_enabled():
+    return str(os.environ.get(WORKER_ENV, "1")).lower() not in ("0", "false", "no")
+
+
+def _run_worker(payload, timeout):
+    """Run one request in a killed subprocess; returns the backend payload."""
+    base = os.path.join(tempfile.gettempdir(), "calcbox-runs")
+    os.makedirs(base, exist_ok=True)          # ordinary dir: no restrictive DACL
+    run_dir = os.path.join(base, "run-%d-%d" % (os.getpid(), time.time_ns()))
+    os.makedirs(run_dir, exist_ok=True)
+    in_path = os.path.join(run_dir, "in.json")
+    out_path = os.path.join(run_dir, "out.json")
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    try:
+        with open(in_path, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh)
+        env = os.environ.copy()
+        env["PYTHONPATH"] = root + os.pathsep + env.get("PYTHONPATH", "")
+        env["CALCBOX_SANDBOX_TEMP"] = run_dir
+        env["TMP"] = env["TEMP"] = env["TMPDIR"] = run_dir
+        env["PYTHONDONTWRITEBYTECODE"] = "1"
+        os.makedirs(os.path.join(run_dir, "mpl"), exist_ok=True)
+        env["MPLCONFIGDIR"] = os.path.join(run_dir, "mpl")
+        env["MPLBACKEND"] = "Agg"
+        cmd = [sys.executable, "-m", "calcbox.worker", in_path, out_path]
+        proc = subprocess.Popen(cmd, cwd=run_dir, env=env,
+                                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        try:
+            code = proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=5)
+            raise ComputeError("computation timed out")
+        if not os.path.exists(out_path):
+            raise ComputeError("compute worker produced no output (exit %s)" % code)
+        with open(out_path, encoding="utf-8") as fh:
+            body = json.load(fh)
+        if not body.get("ok"):
+            if body.get("kind") == "unavailable":
+                raise BackendUnavailable(body.get("error") or "backend unavailable")
+            raise ComputeError(body.get("error") or "computation failed")
+        return body["out"]
+    finally:
+        shutil.rmtree(run_dir, ignore_errors=True)
+
+
+
+def _scipy_func(expr, var):
+    import sympy as sp
+
+    local = _locals(var)
+    e = sp.sympify(expr.replace("^", "**"), locals=local)
+    return sp.lambdify(local[var], e, "numpy"), e, local[var]
+
+
+def _scipy(expr, op, var, point, target, timeout):
+    import sympy as sp
+
+    if not _available("scipy"):
+        raise BackendUnavailable("scipy is not installed")
+    if op not in OPS_NUMERIC:
+        raise ComputeError("scipy operation must be one of %s" % sorted(OPS_NUMERIC))
+    f, e, sym = _scipy_func(expr, var)
+    try:
+        if op == "quad":
+            from scipy.integrate import quad
+            lo = float(sp.sympify(point).evalf())
+            hi = float(sp.sympify(target or "1").evalf())
+            value, err = quad(lambda x: float(f(x)), lo, hi)
+            cross = None
+            try:
+                exact = float(sp.N(sp.integrate(e, (sym, lo, hi))))
+                cross = {"backend": "sympy", "value": exact,
+                         "difference": abs(exact - value)}
+            except Exception:
+                cross = None
+            disputed = bool(cross and cross["difference"] > max(
+                1e-6, 1e-6 * abs(cross["value"])))
+            return {"result": value, "latex": sp.latex(e), "numeric": value,
+                    "details": {"lower": lo, "upper": hi, "error": err},
+                    "cross_check": cross, "disputed": disputed}
+        if op == "minimize":
+            from scipy.optimize import minimize
+            x0 = float(sp.sympify(point or "0").evalf())
+            res = minimize(lambda x: float(f(x[0])), [x0])
+            return {"result": float(res.x[0]), "latex": sp.latex(e),
+                    "numeric": float(res.fun),
+                    "details": {"success": bool(res.success),
+                                "iterations": int(res.nit)}}
+        if op == "root":
+            from scipy.optimize import root_scalar
+            lo = float(sp.sympify(point or "0").evalf())
+            hi = float(sp.sympify(target or "1").evalf())
+            res = root_scalar(lambda x: float(f(x)), bracket=(lo, hi))
+            return {"result": float(res.root), "latex": sp.latex(e),
+                    "numeric": 0.0,
+                    "details": {"converged": bool(res.converged),
+                                "bracket": [lo, hi]}}
+    except ComputeError:
+        raise
+    except Exception as e:
+        raise ComputeError(str(e))
+    raise ComputeError("unknown scipy operation")
+
+
+def _pint(expr, op, target, timeout):
+    if not _available("pint"):
+        raise BackendUnavailable("pint is not installed; pip install pint")
+    if op != "convert":
+        raise ComputeError("pint operation must be convert")
+    if not target:
+        raise ComputeError("target unit is required for convert")
+    if not re.fullmatch(r"[0-9A-Za-z .,*/^()_+-]+", expr):
+        raise ComputeError("unit expression contains invalid characters")
+    try:
+        import pint
+
+        ureg = pint.UnitRegistry()
+        value = ureg(expr)
+        out = value.to(target)
+        return {"result": str(out), "latex": "",
+                "numeric": float(out.magnitude),
+                "details": {"magnitude": float(out.magnitude),
+                            "units": str(out.units)}}
+    except Exception as e:
+        raise ComputeError(str(e))
+
+
+def _control(data, op, timeout):
+    if not _available("control"):
+        raise BackendUnavailable("control is not installed; pip install control")
+    if op != "step":
+        raise ComputeError("control operation must be step")
+    data = data or {}
+    num, den = data.get("num"), data.get("den")
+    if (not isinstance(num, list) or not isinstance(den, list)
+            or not num or not den
+            or not all(isinstance(x, (int, float)) for x in num + den)):
+        raise ComputeError("control step needs data.num and data.den number lists")
+    # matplotlib (a control dependency) writes a cache on import; keep it in a
+    # directory the sandbox allows.
+    os.environ.setdefault("MPLBACKEND", "Agg")
+    cache = os.environ.get("CALCBOX_SANDBOX_TEMP") or os.path.join(
+        tempfile.gettempdir(), "calcbox-mpl")
+    try:
+        os.makedirs(cache, exist_ok=True)
+        os.environ.setdefault("MPLCONFIGDIR", os.path.join(cache, "mpl"))
+    except OSError:
+        pass
+    try:
+        import control
+
+        sys = control.TransferFunction(num, den)
+        tf = control.step_info(sys)
+        return {"result": str(sys), "latex": "",
+                "numeric": float(tf.get("SteadyStateValue", 0.0)),
+                "details": {k: (float(v) if isinstance(v, (int, float)) else v)
+                            for k, v in tf.items()}}
+    except Exception as e:
+        raise ComputeError(str(e))
+
+
+
+def _wolfram(expr, op, timeout):
+    if not _external_enabled():
+        raise BackendUnavailable("external backends disabled; set %s=1" % EXTERNAL_ENV)
+    exe = _which(("wolframscript", "WolframKernel"))
+    if not exe:
+        raise BackendUnavailable("Wolfram Engine/wolframscript not found")
+    if op != "eval":
+        raise ComputeError("wolfram operation must be eval")
+    if len(expr) > 2000:
+        raise ComputeError("wolfram expression too long")
+    try:
+        proc = subprocess.run([exe, "-code", expr], capture_output=True,
+                              text=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        raise ComputeError("wolfram computation timed out")
+    except Exception as e:
+        raise ComputeError(str(e))
+    out = (proc.stdout or "").strip()
+    if proc.returncode != 0 and not out:
+        raise ComputeError((proc.stderr or "wolfram failed").strip()[:300])
+    return {"result": out, "latex": "", "numeric": None,
+            "details": {"returncode": proc.returncode}}
+
+
+def _lean(code, op, timeout):
+    if not _external_enabled():
+        raise BackendUnavailable("external backends disabled; set %s=1" % EXTERNAL_ENV)
+    exe = _which(("lean", "lake"))
+    if not exe:
+        raise BackendUnavailable("Lean 4/lake not found")
+    if op != "check":
+        raise ComputeError("lean operation must be check")
+    if len(code) > 5000:
+        raise ComputeError("lean code too long")
+    base = os.environ.get("CALCBOX_SANDBOX_TEMP") or tempfile.gettempdir()
+    os.makedirs(base, exist_ok=True)
+    path = os.path.join(base, "check-%d.lean" % time.time_ns())
+    try:
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(code)
+        try:
+            proc = subprocess.run([exe, path], capture_output=True, text=True,
+                                  timeout=timeout)
+        except subprocess.TimeoutExpired:
+            raise ComputeError("lean check timed out")
+        return {"result": "ok" if proc.returncode == 0 else "failed",
+                "latex": "", "numeric": None,
+                "details": {"returncode": proc.returncode,
+                            "stdout": (proc.stdout or "")[:1000],
+                            "stderr": (proc.stderr or "")[:1000]}}
+    finally:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+
+
+def _execute_local(backend, expression, operation, variable="x", point="0",
+                   target=None, data=None, timeout=8.0):
+    """Run one backend in-process. Policy lives in calcbox.sandbox."""
+    if backend == "sympy":
+        payload = {"backend": backend, "expression": expression,
+                   "operation": operation, "variable": variable, "point": point,
+                   "target": target, "data": data, "timeout": timeout}
+        if _worker_enabled():
+            return _run_worker(payload, timeout)
+        expression = _validate(expression)
+        point = _validate(point, 100)
+        if target:
+            target = _validate(target, 100)
+        if not re.fullmatch(r"[A-Za-z]", variable or ""):
+            raise ComputeError("variable must be one letter")
+        return _sympy(expression, operation, variable, point, target, timeout)
+    if backend == "scipy":
+        expression = _validate(expression)
+        point = _validate(point, 100)
+        if target:
+            target = _validate(target, 100)
+        if not re.fullmatch(r"[A-Za-z]", variable or ""):
+            raise ComputeError("variable must be one letter")
+        return _scipy(expression, operation, variable, point, target, timeout)
+    if backend == "pint":
+        expression = _validate(expression)
+        return _pint(expression, operation, target, timeout)
+    if backend == "control":
+        return _control(data, operation, timeout)
+    if backend == "wolfram":
+        return _wolfram(expression, operation, timeout)
+    if backend == "lean":
+        return _lean(expression, operation, timeout)
+    raise BackendUnavailable("external backend %r disabled or not implemented" % backend)
+
+
+def _assumptions(backend, variable, point, target, data):
+    if backend == "sympy":
+        return {"variable": variable, "domain": "complex"}
+    return {"external": True}
+
+
+def compute(expression, operation="simplify", variable="x", point="0",
+            target=None, data=None, timeout=8.0, backend="auto"):
+    """Compute one expression; returns a dict shaped by calcbox.contract."""
+    t0 = time.perf_counter()
+    status = backend_status()
+    backend = (backend or "auto").lower()
+    if backend == "auto":
+        backend = infer_backend(operation)
+    if backend not in status:
+        raise ComputeError("unknown backend %r" % backend)
+    if not status[backend]["available"]:
+        raise BackendUnavailable(status[backend].get("reason") or
+                                 "backend %r is not available" % backend)
+    timeout = min(max(float(timeout), 0.1), 60.0)
+    req = ComputeRequest(expression=expression, operation=operation,
+                         variable=variable, point=point, target=target,
+                         data=data, timeout=timeout, backend=backend)
+    payload = req.payload()
+    if backend in ("wolfram", "lean"):
+        _execute_in_process = True   # already external processes; no nested worker
+    if backend in ("sympy", "scipy") and _worker_enabled():
+        out = _run_worker(payload, timeout)
+    elif backend == "pint" and _worker_enabled():
+        out = _run_worker(payload, timeout)
+    else:
+        out = _execute_local(**payload)
+    digest = hashlib.sha256(json.dumps(payload, sort_keys=True,
+                                       ensure_ascii=False).encode("utf-8")).hexdigest()
+    generated = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    verification = out.get("verification") or _verification(backend, out)
+    disputed = bool(out.get("disputed"))
+    credentials = {
+        "backend": backend,
+        "engine_version": status[backend].get("version"),
+        "input_sha256": digest,
+        "operation": operation,
+        "assumptions": _assumptions(backend, variable, point, target, data),
+        "verification": verification,
+        "cross_check": out.get("cross_check"),
+        "disputed": disputed,
+        "sandbox": "audit-only",
+        "generated_at": generated,
+    }
+    result = ComputeResult(
+        ok=True, backend=backend, engine_version=status[backend].get("version"),
+        operation=operation, input=expression, variable=variable,
+        result=out["result"], latex=out.get("latex", ""),
+        numeric=out.get("numeric"), details=out.get("details"),
+        cross_check=out.get("cross_check"),
+        assumptions=credentials["assumptions"],
+        verification=verification, disputed=disputed, sandbox="audit-only",
+        credentials=credentials, input_sha256=digest, generated_at=generated,
+        elapsed_ms=round((time.perf_counter() - t0) * 1000, 3),
+    )
+    return result.to_dict()

calcbox/cli.py

@@ -0,0 +1,45 @@
+"""Command line: one expression, JSON (or a short human line) out."""
+import argparse
+import json
+import sys
+
+from .backends import compute as run_compute
+from .contract import BackendUnavailable, ComputeError
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="calcbox",
+                                 description="compute one expression with provenance")
+    ap.add_argument("expression")
+    ap.add_argument("--op", default="simplify")
+    ap.add_argument("--var", default="x")
+    ap.add_argument("--point", default="0")
+    ap.add_argument("--target", default=None)
+    ap.add_argument("--backend", default="auto")
+    ap.add_argument("--timeout", type=float, default=8.0)
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    try:
+        out = run_compute(args.expression, operation=args.op,
+                               variable=args.var, point=args.point,
+                               target=args.target, timeout=args.timeout,
+                               backend=args.backend)
+    except BackendUnavailable as e:
+        print("backend unavailable: %s" % e, file=sys.stderr)
+        return 3
+    except ComputeError as e:
+        print("bad request: %s" % e, file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+    else:
+        print("%s = %s   [%s %s, %.1f ms]" % (
+            out["input"], out["result"], out["backend"],
+            out["engine_version"] or "?", out["elapsed_ms"]))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

calcbox/contract.py

@@ -0,0 +1,118 @@
+"""calcbox wire contract.
+
+One dict shape is shared by the Python API, the HTTP router, the MCP server and
+the CLI. Anything that changes here is a breaking change.
+
+Successful result:
+    {
+      "ok": true,
+      "backend": "sympy",
+      "engine_version": "1.13.3",
+      "operation": "integrate",
+      "input": "x**2",
+      "variable": "x",
+      "result": "x**3/3",
+      "latex": "\\frac{x^{3}}{3}",
+      "numeric": null,
+      "assumptions": {"variable": "x", "domain": "complex"},
+      "verification": {"method": "differentiate-back", "passed": true},
+      "disputed": false,
+      "sandbox": "audit-only",
+      "credentials": {"backend": "sympy", "verification": {...}, "sandbox": "audit-only"},
+      "input_sha256": "…",
+      "generated_at": "2026-11-11T09:00:00Z",
+      "elapsed_ms": 12.4
+    }
+
+Failure: ComputeError (client error) or BackendUnavailable (missing dependency
+or disabled external backend). Transports map them to 400 / 503.
+"""
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+OPS_SYMBOLIC = {"simplify", "diff", "integrate", "solve", "limit", "value",
+                "latex", "factor", "expand"}
+OPS_NUMERIC = {"quad", "minimize", "root"}
+OPS_UNITS = {"convert"}
+OPS_CONTROL = {"step"}
+OPS_EXTERNAL = {"eval", "check"}
+
+BACKENDS = ("sympy", "scipy", "pint", "control", "wolfram", "lean")
+
+
+class ComputeError(ValueError):
+    """The request is invalid (bad expression, unknown operation, bad backend)."""
+
+
+class BackendUnavailable(ComputeError):
+    """The backend exists but cannot serve: dependency missing or not enabled."""
+
+
+@dataclass
+class ComputeRequest:
+    expression: str
+    operation: str = "simplify"
+    variable: str = "x"
+    point: str = "0"
+    target: Optional[str] = None
+    data: Optional[Dict[str, Any]] = None
+    timeout: float = 8.0
+    backend: str = "auto"
+
+    def payload(self) -> Dict[str, Any]:
+        return {"backend": self.backend, "expression": self.expression,
+                "operation": self.operation, "variable": self.variable,
+                "point": self.point, "target": self.target, "data": self.data,
+                "timeout": self.timeout}
+
+
+@dataclass
+class ComputeResult:
+    ok: bool
+    backend: str
+    engine_version: Optional[str]
+    operation: str
+    input: str
+    variable: str
+    result: Any
+    latex: str = ""
+    numeric: Any = None
+    details: Optional[Dict[str, Any]] = None
+    cross_check: Optional[Dict[str, Any]] = None
+    assumptions: Dict[str, Any] = field(default_factory=dict)
+    verification: Dict[str, Any] = field(default_factory=dict)
+    disputed: bool = False
+    sandbox: str = "audit-only"
+    credentials: Dict[str, Any] = field(default_factory=dict)
+    input_sha256: str = ""
+    generated_at: str = ""
+    elapsed_ms: float = 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "ok": self.ok, "backend": self.backend,
+            "engine_version": self.engine_version, "operation": self.operation,
+            "input": self.input, "variable": self.variable,
+            "result": self.result, "latex": self.latex,
+            "numeric": self.numeric, "details": self.details,
+            "cross_check": self.cross_check, "assumptions": self.assumptions,
+            "verification": self.verification, "disputed": self.disputed,
+            "sandbox": self.sandbox, "credentials": self.credentials,
+            "input_sha256": self.input_sha256,
+            "generated_at": self.generated_at, "elapsed_ms": self.elapsed_ms,
+        }
+
+
+@dataclass
+class BackendStatus:
+    available: bool
+    version: Optional[str] = None
+    reason: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"available": self.available}
+        if self.version:
+            out["version"] = self.version
+        if self.reason:
+            out["reason"] = self.reason
+        return out

calcbox/mcp_server.py

@@ -0,0 +1,87 @@
+"""MCP server (stdio).
+
+Exposes two tools, matching the HTTP contract:
+
+    compute(expression, operation, variable, point, target, backend)
+    backends()
+
+Requires the optional extra:  pip install "calcbox[mcp]".
+"""
+import json
+import sys
+
+from . import backends as _backends
+from .contract import BackendUnavailable, ComputeError
+
+INSTRUCTIONS = (
+    "A calculator that reports provenance. Prefer it over mental arithmetic for "
+    "calculus, algebra and unit conversion. Read the verification field before "
+    "quoting a result; disputed=true means a cross-check disagreed."
+)
+
+
+def main(argv=None):
+    try:
+        from mcp.server import Server
+        from mcp.server.stdio import stdio_server
+        from mcp.types import TextContent, Tool
+    except ImportError:
+        print('calcbox-mcp needs the mcp extra: pip install "calcbox[mcp]"',
+              file=sys.stderr)
+        return 2
+
+    server = Server("calcbox", instructions=INSTRUCTIONS)
+
+    @server.list_tools()
+    async def list_tools():
+        return [
+            Tool(name="compute",
+                 description="Evaluate one expression and return the result with "
+                             "backend, version, assumptions and verification.",
+                 inputSchema={
+                     "type": "object",
+                     "properties": {
+                         "expression": {"type": "string"},
+                         "operation": {"type": "string", "default": "simplify"},
+                         "variable": {"type": "string", "default": "x"},
+                         "point": {"type": "string", "default": "0"},
+                         "target": {"type": "string"},
+                         "backend": {"type": "string", "default": "auto"},
+                     },
+                     "required": ["expression"],
+                 }),
+            Tool(name="backends",
+                 description="Which backends are available and why.",
+                 inputSchema={"type": "object", "properties": {}}),
+        ]
+
+    @server.call_tool()
+    async def call_tool(name, arguments):
+        if name == "backends":
+            payload = {"backends": _backends.backend_status()}
+        elif name == "compute":
+            try:
+                payload = _backends.compute(
+                    arguments["expression"],
+                    operation=arguments.get("operation", "simplify"),
+                    variable=arguments.get("variable", "x"),
+                    point=arguments.get("point", "0"),
+                    target=arguments.get("target"),
+                    backend=arguments.get("backend", "auto"))
+            except (ComputeError, BackendUnavailable) as e:
+                payload = {"ok": False, "error": type(e).__name__, "detail": str(e)}
+        else:
+            payload = {"ok": False, "error": "unknown tool"}
+        return [TextContent(type="text", text=json.dumps(payload, ensure_ascii=False))]
+
+    async def run():
+        async with stdio_server() as (read, write):
+            await server.run(read, write, server.create_initialization_options())
+
+    import asyncio
+    asyncio.run(run())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

calcbox/sandbox.py

@@ -0,0 +1,78 @@
+"""Audit-only sandbox for the compute worker.
+
+Blocks, at the Python level: network sockets, process creation, and any
+filesystem write outside the per-run temp directory. There is no namespace, no
+seccomp, no read-only mount — a determined expression can still consume CPU or
+memory. Reported as sandbox="audit-only" so nobody mistakes it for isolation.
+
+Ported from socratic-tutor's sandbox_policy.py; the only change is the
+environment variable name (CALCBOX_SANDBOX_TEMP).
+"""
+import os
+import sys
+
+TEMP_ENV = "CALCBOX_SANDBOX_TEMP"
+
+_NETWORK = ("socket.__new__", "socket.connect", "socket.bind",
+            "socket.getaddrinfo", "socket.gethostbyname", "socket.sendto")
+_PROCESS = ("subprocess.Popen", "os.system", "os.exec", "os.spawn",
+            "os.posix_spawn", "os.fork")
+_WRITE_EVENTS = ("os.remove", "os.unlink", "os.mkdir", "os.rmdir", "os.chmod",
+                 "os.utime", "os.truncate")
+_RENAME_EVENTS = ("os.rename", "os.replace")
+
+
+class PolicyViolation(PermissionError):
+    """Raised from the audit hook when the policy denies an operation."""
+
+
+def status():
+    return {"available": True, "mode": "audit-only",
+            "network": "denied-by-policy",
+            "subprocess": "denied-by-policy",
+            "filesystem": "temp-only",
+            "note": "audit hooks are advisory; run real workloads in a container"}
+
+
+def install(temp):
+    temp = os.path.realpath(temp or "")
+    if not temp:
+        raise RuntimeError("sandbox temp is required")
+
+    def inside(path):
+        if path is None or isinstance(path, int):
+            return False
+        try:
+            p = os.path.realpath(str(path))
+        except Exception:
+            return False
+        return p == temp or p.startswith(temp + os.sep)
+
+    def hook(event, args):
+        if event in _NETWORK:
+            raise PermissionError("network disabled by compute sandbox")
+        if event in _PROCESS:
+            raise PermissionError("process creation disabled by compute sandbox")
+        if event == "open":
+            path = args[0] if args else None
+            mode = args[1] if len(args) > 1 else "r"
+            flags = args[2] if len(args) > 2 else 0
+            writing = False
+            if isinstance(mode, str):
+                writing = any(c in mode for c in "wax+")
+            elif isinstance(flags, int):
+                writing = bool(flags & (os.O_WRONLY | os.O_RDWR |
+                                        os.O_CREAT | os.O_APPEND))
+            if writing and not inside(path):
+                raise PermissionError("read-only filesystem: %s" % (path,))
+        if event in _WRITE_EVENTS:
+            path = args[0] if args else None
+            if path is not None and not inside(path):
+                raise PermissionError("read-only filesystem: %s" % (path,))
+        if event in _RENAME_EVENTS:
+            for path in args[:2]:
+                if path is not None and not inside(path):
+                    raise PermissionError("read-only filesystem: %s" % (path,))
+
+    sys.addaudithook(hook)
+    return status()

calcbox/worker.py

@@ -0,0 +1,49 @@
+"""Subprocess worker: one request in, one response out.
+
+Runs in its own process so a timeout can kill it without taking the caller down
+(an in-process thread cannot be cancelled, and a stuck SymPy integral would keep
+the interpreter alive at exit). The parent writes JSON to a file, spawns us with
+that path and a result path, and reads the reply back.
+"""
+import json
+import os
+import sys
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if len(argv) != 2:
+        return 2
+    in_path, out_path = argv
+    with open(in_path, encoding="utf-8") as fh:
+        payload = json.load(fh)
+
+    try:
+        from .sandbox import install
+        install(os.environ.get("CALCBOX_SANDBOX_TEMP") or os.path.dirname(in_path))
+    except Exception as e:  # policy problems must not look like compute errors
+        body = {"ok": False, "kind": "internal",
+                "error": "sandbox install failed: %s" % e}
+        with open(out_path, "w", encoding="utf-8") as fh:
+            json.dump(body, fh)
+        return 1
+
+    # Inside the worker we are already the sandboxed process: never re-spawn.
+    os.environ["CALCBOX_WORKER"] = "0"
+    from .backends import BackendUnavailable, ComputeError, _execute_local
+    try:
+        out = _execute_local(**payload)
+        body = {"ok": True, "out": out}
+    except BackendUnavailable as e:
+        body = {"ok": False, "kind": "unavailable", "error": str(e)}
+    except ComputeError as e:
+        body = {"ok": False, "kind": "compute", "error": str(e)}
+    except Exception as e:
+        body = {"ok": False, "kind": "internal", "error": str(e)[:300]}
+    with open(out_path, "w", encoding="utf-8") as fh:
+        json.dump(body, fh, ensure_ascii=False)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

calcbox-0.3.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: calcbox
+Version: 0.3.0
+Summary: Backend-agnostic math compute kernel: symbolic, numeric, units, control — with provenance in every answer
+Author: calcbox contributors
+License: MIT
+Project-URL: Repository, https://github.com/Icefox12138/calcbox
+Keywords: math,sympy,scipy,units,mcp,compute
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: symbolic
+Requires-Dist: sympy>=1.12; extra == "symbolic"
+Provides-Extra: numeric
+Requires-Dist: scipy>=1.11; extra == "numeric"
+Requires-Dist: numpy; extra == "numeric"
+Provides-Extra: units
+Requires-Dist: pint>=0.23; extra == "units"
+Provides-Extra: control
+Requires-Dist: control>=0.9; extra == "control"
+Requires-Dist: numpy; extra == "control"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == "api"
+Requires-Dist: pydantic>=2; extra == "api"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: full
+Requires-Dist: sympy>=1.12; extra == "full"
+Requires-Dist: scipy>=1.11; extra == "full"
+Requires-Dist: numpy; extra == "full"
+Requires-Dist: pint>=0.23; extra == "full"
+Requires-Dist: control>=0.9; extra == "full"
+Dynamic: license-file
+
+# calcbox
+
+Backend-agnostic math compute kernel: **symbolic, numeric, units, control** — and every
+answer carries provenance (backend, engine version, assumptions, verification, input hash).
+
+It knows nothing about teaching, documents or users. It is a calculator that can prove
+what it did.
+
+```python
+from calcbox import compute
+
+out = compute("x**2", "integrate")
+# {'result': 'x**3/3', 'backend': 'sympy', 'engine_version': '1.13.1',
+#  'verification': {'method': 'differentiate-back', 'passed': True}, ...}
+```
+
+## Why another math tool
+
+There are MCP servers that evaluate arithmetic and matrix operations. What they do not
+report is **how the answer was produced**: which backend, which engine version, which
+assumptions, and whether a second method agreed. For tutoring, for reproducible
+research notes, and for anything a human will quote, that provenance is the point.
+
+```json
+{
+  "result": "x**3/3",
+  "latex": "\\frac{x^{3}}{3}",
+  "backend": "sympy",
+  "engine_version": "1.13.1",
+  "assumptions": {"variable": "x", "domain": "real"},
+  "verification": {"method": "differentiate-back", "passed": true},
+  "disputed": false,
+  "sandbox": "audit-only",
+  "input_sha256": "9f2c…",
+  "elapsed_ms": 12.4
+}
+```
+
+## Install
+
+```bash
+pip install calcbox              # core, no backends
+pip install "calcbox[symbolic]"  # sympy  (calculus, algebra, exact values)
+pip install "calcbox[full]"      # sympy + scipy + pint + control
+pip install "calcbox[mcp]"       # MCP server (stdio)
+pip install "calcbox[api]"       # FastAPI router
+```
+
+Nothing is a hard dependency. A missing backend is reported as unavailable **with a
+reason**, never as a crash.
+
+## Use it
+
+**Python**
+
+```python
+compute("x**2", "integrate")            # indefinite
+compute("x", "integrate", target="0,1") # definite
+compute("x**3", "diff")
+compute("2+3*4", "value")
+compute("x**2-1", "solve")
+compute("sin(x)/x", "limit", point="0")
+compute("x**2", "simplify", backend="sympy")
+```
+
+**CLI**
+
+```bash
+calcbox "x**2" --op integrate
+calcbox "sin(x)/x" --op limit --point 0 --json
+```
+
+**HTTP** (optional; no auth by design — that belongs to the host)
+
+```python
+from fastapi import FastAPI
+from calcbox.api import create_router
+
+app = FastAPI()
+app.include_router(create_router())
+# GET  /v1/compute/backends
+# POST /v1/compute {"expression": "x**2", "operation": "integrate"}
+```
+
+**MCP**
+
+```json
+{
+  "mcpServers": {
+    "calcbox": {"command": "calcbox-mcp", "args": []}
+  }
+}
+```
+
+Tools: `compute`, `backends`.
+
+## Contract
+
+| Field | Meaning |
+|---|---|
+| `operation` | `simplify`, `diff`, `integrate`, `solve`, `limit`, `value`, `latex`, `factor`, `expand`, `quad`, `minimize`, `root`, `convert`, `step`, `eval`, `check` |
+| `backend` | `auto` infers from the operation; otherwise one of `sympy`/`scipy`/`pint`/`control`/`wolfram`/`lean` |
+| `verification` | method + `passed`; e.g. differentiate-back for integrals, substitute-back for solutions |
+| `disputed` | two backends disagreed (only when a cross-check runs) |
+| `sandbox` | always `audit-only` for in-process backends |
+
+Errors: `ComputeError` (bad request → 400) and `BackendUnavailable` (missing dependency
+or disabled external engine → 503).
+
+## Security
+
+**The sandbox is audit-only.** It is a set of `sys.audit` hooks, not an OS jail. Read
+[SECURITY.md](SECURITY.md) before exposing this to untrusted input. External engines
+(Wolfram, Lean) are disabled unless `CALCBOX_EXTERNAL=1`.
+
+## Status
+
+0.3.0 — all six backends wired: SymPy, SciPy, Pint, Control, and the external
+engines Wolfram and Lean (disabled unless CALCBOX_EXTERNAL=1; both fail with a
+reason when the binary is absent, never silently).
+
+15/15 parity with the implementation this was ported from, 36 tests.
+
+Every local call runs in a killable subprocess worker (~0.2-1.2 s overhead);
+CALCBOX_WORKER=0 runs in-process for debugging. External engines run in-process
+because they are already separate processes.
+
+## Releasing
+
+See [RELEASING.md](RELEASING.md): PyPI Trusted Publishing, no tokens.
+
+## License
+
+MIT.

calcbox-0.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+calcbox/__init__.py,sha256=cYlvY7cncEgrbLlsdzFaAN-KbaYjmGdeCmfXfDCcUo0,746
+calcbox/api.py,sha256=k4dEl0t2A1L9ji1TPQaRde6zSVHxKrRJKMw-lB_R8ME,1786
+calcbox/backends.py,sha256=1iJLMgqGQbKas72nzTFqPkUzZm7rp-gq_Sn00UwhXxw,23270
+calcbox/cli.py,sha256=Rhxhb7Ajgi81dt1UMKwLY5kD9SZr0M_u7Z2e5UnMnPg,1573
+calcbox/contract.py,sha256=7mEdPztEv3MuszNLJAjeHWEzqrGRqiAVOHPmQY50fNk,3896
+calcbox/mcp_server.py,sha256=A-IoT6KwBZLNEwLKT8rocH9WjWnQJd7IcL2e7fNAQYQ,3195
+calcbox/sandbox.py,sha256=MqYzs_-tN11bAndfMEM9RHPdSVZ1uQuBlOt3XrI7mpU,3051
+calcbox/worker.py,sha256=5DLyGoztuQRxoDrhkjMrpJTpUNyrFRmbBI7MTH5Y0Qk,1791
+calcbox-0.3.0.dist-info/licenses/LICENSE,sha256=b2suCwCCZ7EX3q3OzfpU-zmjQ9SDadaXPsadFU8PG-s,1077
+calcbox-0.3.0.dist-info/METADATA,sha256=YXDAglRalrAHGBfTBtKEFVNElixYwyeNE7WuTNgZIvw,5390
+calcbox-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+calcbox-0.3.0.dist-info/entry_points.txt,sha256=TIKPxSXTtstrjuZA86aIZiLNRwpVWcAB4LZEUNJQ-TM,83
+calcbox-0.3.0.dist-info/top_level.txt,sha256=TZlAzqt-_wCAGeffKUREylBsoGvxb8bEmeUS2YoUimQ,8
+calcbox-0.3.0.dist-info/RECORD,,

calcbox-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

calcbox-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+calcbox = calcbox.cli:main
+calcbox-mcp = calcbox.mcp_server:main

calcbox-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calcbox contributors
+
+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.

calcbox-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+calcbox