pycodemath 0.2.0__tar.gz → 0.3.0__tar.gz

{pycodemath-0.2.0 → pycodemath-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycodemath
-Version: 0.2.0
+Version: 0.3.0
 Summary: Token-efficient exact math for AI agents: symbolic engine, ODE suite, optimizer and an optimized-code generator (SymPy + NumPy).
 Author: cybersora
 License: MIT
@@ -11,6 +11,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -21,7 +22,7 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0; extra == "mcp"
+Requires-Dist: mcp<2.0,>=1.0; extra == "mcp"
 Dynamic: license-file
 
 <p align="center">
@@ -36,13 +37,18 @@ Dynamic: license-file
 </p>
 
 <p align="center">
+  <a href="https://pypi.org/project/pycodemath/"><img alt="PyPI" src="https://img.shields.io/pypi/v/pycodemath.svg?color=e11d33"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-e11d33.svg"></a>
   <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-3776ab.svg">
-  <img alt="230 tests passing" src="https://img.shields.io/badge/tests-230%20passing-2ea043.svg">
+  <img alt="668 tests passing" src="https://img.shields.io/badge/tests-668%20passing-2ea043.svg">
   <img alt="mypy: clean" src="https://img.shields.io/badge/mypy-clean-2ea043.svg">
   <a href="https://github.com/cybersora9/pycodemath/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/cybersora9/pycodemath/actions/workflows/ci.yml/badge.svg"></a>
 </p>
 
+<p align="center">
+  <img alt="pycodemath demo — one command in, one exact result out" src="assets/demo.svg" width="760">
+</p>
+
 Write math in a few characters, get an exact answer or standalone, optimized
 Python/NumPy code back — instead of asking a language model to "do arithmetic
 in its head" or to hand-write numerical loops.
@@ -64,9 +70,14 @@ text → [parser] → IR (expression tree) → [engine]     evaluate / simplify
 ## Install
 
 ```bash
-pip install -e .                  # core: sympy + numpy
-pip install -e .[mcp]             # + MCP server for AI agents
-pip install -e .[dev]             # + pytest
+pip install pycodemath            # core: sympy + numpy
+pip install pycodemath[mcp]       # + MCP server for AI agents
+```
+
+From a clone, for development (editable install):
+
+```bash
+pip install -e .[dev]             # editable + pytest + mypy
 ```
 
 Requires Python ≥ 3.11.
@@ -308,6 +319,53 @@ ev = solve_ode_events(parse("cos(t)"), "t", 0.0, (0.0, 10.0), parse("y"), rtol=1
 ev.event_times   # -> [3.141593, 6.283185, 9.424778]   (π, 2π, 3π)
 ```
 
+## Structured results: the evidence behind the answer
+
+Every solver in this package now has a `full_result=True` form that returns
+evidence instead of a bare number — a frozen `SolveResult` (value,
+iterations, residual, converged, status) for `root_find` / `root_find_nd` /
+`minimize` / `minimize_nd`, and a `QuadratureResult` (adds `error_estimate`)
+for `integrate_num`. Default calls are unchanged, bit-identical to before.
+
+```pycon
+>>> from pycodemath import root_find, minimize, integrate_num, parse
+>>> root_find(parse("x^2 - 2"), "x", 1.0, full_result=True)
+SolveResult(value=1.4142135623746899, iterations=5, residual=4.510614104447086e-12, converged=True, status='converged')
+
+>>> minimize(parse("-x^2"), "x", 1.0, full_result=True)
+SolveResult(value=1085298990978.309, iterations=152, residual=2170597981956.618, converged=False, status='diverged')
+
+>>> integrate_num(parse("sqrt(x)"), "x", 0.0, 1.0, tol=1e-10, full_result=True)
+QuadratureResult(value=0.6666666666666469, error_estimate=2.4271240969151142e-11, evaluations=1005, refinements=201, converged=True, status='converged')
+```
+
+`converged` is the only field worth branching on, and it is corroborated, not
+just "the tolerance test fired": a vanishing gradient at a saddle or a
+maximum reports `status='not_a_minimum'` rather than a false convergence.
+
+The MCP server carries the same structure over the wire as `structuredContent`
+(`text` / `solve` / `quadrature` / `error` fields), not just prose — a client
+validates it against the declared schema instead of parsing text.
+
+**Trailing options** put those same knobs on the REPL/one-shot grammar:
+
+```console
+$ python -m pycodemath "min x^4 for x at 1 tol 1e-5"
+0.029229144526165384
+
+$ python -m pycodemath "nintegrate sqrt(x) dx from 0 to 1 tol 1e-10"
+0.6666666666666469
+```
+
+`tol <t>` (on `min` / `min_nd` / `nintegrate`), `max_iter <k>` (on `min` /
+`min_nd`) and `budget <s>` (on the symbolic commands, bounding a call the
+same way `pycodemath.time_budget(seconds)` does in Python) are `key value`
+pairs at the end of a command, in any order.
+
+A symbolic call that refuses says which of two things happened:
+`NoClosedFormError` (the engine searched and found nothing — try numerically)
+or `UnsupportedFormError` (no method exists for this shape at all).
+
 ## Design contracts
 
 - One IR (`Expr`/`Matrix`) shared by the engine and the generator.
@@ -320,7 +378,11 @@ ev.event_times   # -> [3.141593, 6.283185, 9.424778]   (π, 2π, 3π)
   access are rejected outright, and evaluation cost is bounded so a single
   expression (e.g. `9**9**9`) can't exhaust memory.
 - Tests measure real numbers first, then assert them with a margin —
-  **230 tests**, all green, on Ubuntu and Windows (CI + mypy included).
+  **668 tests**, all green, on Ubuntu and Windows (CI + mypy included).
+- Every failure is a specific `PycodemathError` subclass (`ParseError`,
+  `DomainError`, `DivergenceError`, `StagnationError`, `NonConvergenceError`,
+  `NoClosedFormError`, `UnsupportedFormError`, `TimeBudgetError`) — a caller
+  can catch the mathematical outcome, not string-match a message.
 
 ## License
 

{pycodemath-0.2.0 → pycodemath-0.3.0}/README.md

@@ -10,13 +10,18 @@
 </p>
 
 <p align="center">
+  <a href="https://pypi.org/project/pycodemath/"><img alt="PyPI" src="https://img.shields.io/pypi/v/pycodemath.svg?color=e11d33"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-e11d33.svg"></a>
   <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-3776ab.svg">
-  <img alt="230 tests passing" src="https://img.shields.io/badge/tests-230%20passing-2ea043.svg">
+  <img alt="668 tests passing" src="https://img.shields.io/badge/tests-668%20passing-2ea043.svg">
   <img alt="mypy: clean" src="https://img.shields.io/badge/mypy-clean-2ea043.svg">
   <a href="https://github.com/cybersora9/pycodemath/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/cybersora9/pycodemath/actions/workflows/ci.yml/badge.svg"></a>
 </p>
 
+<p align="center">
+  <img alt="pycodemath demo — one command in, one exact result out" src="assets/demo.svg" width="760">
+</p>
+
 Write math in a few characters, get an exact answer or standalone, optimized
 Python/NumPy code back — instead of asking a language model to "do arithmetic
 in its head" or to hand-write numerical loops.
@@ -38,9 +43,14 @@ text → [parser] → IR (expression tree) → [engine]     evaluate / simplify
 ## Install
 
 ```bash
-pip install -e .                  # core: sympy + numpy
-pip install -e .[mcp]             # + MCP server for AI agents
-pip install -e .[dev]             # + pytest
+pip install pycodemath            # core: sympy + numpy
+pip install pycodemath[mcp]       # + MCP server for AI agents
+```
+
+From a clone, for development (editable install):
+
+```bash
+pip install -e .[dev]             # editable + pytest + mypy
 ```
 
 Requires Python ≥ 3.11.
@@ -282,6 +292,53 @@ ev = solve_ode_events(parse("cos(t)"), "t", 0.0, (0.0, 10.0), parse("y"), rtol=1
 ev.event_times   # -> [3.141593, 6.283185, 9.424778]   (π, 2π, 3π)
 ```
 
+## Structured results: the evidence behind the answer
+
+Every solver in this package now has a `full_result=True` form that returns
+evidence instead of a bare number — a frozen `SolveResult` (value,
+iterations, residual, converged, status) for `root_find` / `root_find_nd` /
+`minimize` / `minimize_nd`, and a `QuadratureResult` (adds `error_estimate`)
+for `integrate_num`. Default calls are unchanged, bit-identical to before.
+
+```pycon
+>>> from pycodemath import root_find, minimize, integrate_num, parse
+>>> root_find(parse("x^2 - 2"), "x", 1.0, full_result=True)
+SolveResult(value=1.4142135623746899, iterations=5, residual=4.510614104447086e-12, converged=True, status='converged')
+
+>>> minimize(parse("-x^2"), "x", 1.0, full_result=True)
+SolveResult(value=1085298990978.309, iterations=152, residual=2170597981956.618, converged=False, status='diverged')
+
+>>> integrate_num(parse("sqrt(x)"), "x", 0.0, 1.0, tol=1e-10, full_result=True)
+QuadratureResult(value=0.6666666666666469, error_estimate=2.4271240969151142e-11, evaluations=1005, refinements=201, converged=True, status='converged')
+```
+
+`converged` is the only field worth branching on, and it is corroborated, not
+just "the tolerance test fired": a vanishing gradient at a saddle or a
+maximum reports `status='not_a_minimum'` rather than a false convergence.
+
+The MCP server carries the same structure over the wire as `structuredContent`
+(`text` / `solve` / `quadrature` / `error` fields), not just prose — a client
+validates it against the declared schema instead of parsing text.
+
+**Trailing options** put those same knobs on the REPL/one-shot grammar:
+
+```console
+$ python -m pycodemath "min x^4 for x at 1 tol 1e-5"
+0.029229144526165384
+
+$ python -m pycodemath "nintegrate sqrt(x) dx from 0 to 1 tol 1e-10"
+0.6666666666666469
+```
+
+`tol <t>` (on `min` / `min_nd` / `nintegrate`), `max_iter <k>` (on `min` /
+`min_nd`) and `budget <s>` (on the symbolic commands, bounding a call the
+same way `pycodemath.time_budget(seconds)` does in Python) are `key value`
+pairs at the end of a command, in any order.
+
+A symbolic call that refuses says which of two things happened:
+`NoClosedFormError` (the engine searched and found nothing — try numerically)
+or `UnsupportedFormError` (no method exists for this shape at all).
+
 ## Design contracts
 
 - One IR (`Expr`/`Matrix`) shared by the engine and the generator.
@@ -294,7 +351,11 @@ ev.event_times   # -> [3.141593, 6.283185, 9.424778]   (π, 2π, 3π)
   access are rejected outright, and evaluation cost is bounded so a single
   expression (e.g. `9**9**9`) can't exhaust memory.
 - Tests measure real numbers first, then assert them with a margin —
-  **230 tests**, all green, on Ubuntu and Windows (CI + mypy included).
+  **668 tests**, all green, on Ubuntu and Windows (CI + mypy included).
+- Every failure is a specific `PycodemathError` subclass (`ParseError`,
+  `DomainError`, `DivergenceError`, `StagnationError`, `NonConvergenceError`,
+  `NoClosedFormError`, `UnsupportedFormError`, `TimeBudgetError`) — a caller
+  can catch the mathematical outcome, not string-match a message.
 
 ## License
 

pycodemath-0.3.0/pycodemath/__init__.py

@@ -0,0 +1,171 @@
+"""Pycodemath — heavy computational math + Python.
+
+Top-level public API. Everything a caller needs is importable from here:
+
+``parse`` / ``E`` / ``M`` / ``V``
+    text -> the single IR (``Expr`` / ``Matrix``) the engine and the code
+    generator share.
+``symbolic`` / ``linalg`` / ``numerics`` / ``ode``
+    the engines. The numerical entry points that carry structured results are
+    re-exported by name as well: ``root_find``, ``minimize``, ``root_find_nd``,
+    ``minimize_nd``, ``integrate_num``.
+``PycodemathError`` and its eight subclasses
+    what a failure IS, as a type — the thing to branch on instead of reading a
+    message. ``ParseError`` / ``DomainError`` are refusals of the INPUT;
+    ``DivergenceError`` / ``StagnationError`` / ``NonConvergenceError`` /
+    ``NotAMinimumError`` / ``BudgetExhaustedError`` are outcomes of a RUN; and
+    ``TimeBudgetError`` (module 9) is the run that had no outcome at all because
+    the wall clock ran out first.
+``time_budget`` / ``DEFAULT_TIME_BUDGET``
+    how long the symbolic engine may spend before it refuses. Every symbolic entry
+    point is bounded — ``integrate 1/(x^5+x+1) dx`` used to hang forever — and
+    ``with time_budget(seconds):`` is how a caller says in advance how long it is
+    willing to wait.
+``SolveResult`` / ``QuadratureResult`` / ``SolveStatus`` / ``SOLVE_STATUSES``
+    what a run LEARNED, returned by the calls above under ``full_result=True``.
+    ``converged`` is the only field to branch on — and since module 8 it answers
+    the question that was ASKED (a ROOT, a MINIMUM), not merely "did an exit test
+    fire". The package ships ``py.typed``,
+    so the overloads that make ``full_result`` change the return TYPE are visible
+    to an installed caller's type checker — no cast anywhere.
+
+The README documents each of these with runnable examples.
+"""
+
+from __future__ import annotations
+
+from .codegen.pipeline import (
+    CodeArtifact,
+    generate,
+    generate_ode,
+    generate_ode_adaptive,
+    generate_ode_dense,
+    generate_system,
+)
+from .core.budget import DEFAULT_TIME_BUDGET, time_budget
+from .core.errors import (
+    NUMERIC_ROUTES,
+    ROUTES,
+    BudgetExhaustedError,
+    DivergenceError,
+    DomainError,
+    NoClosedFormError,
+    NonConvergenceError,
+    NotAMinimumError,
+    ParseError,
+    PycodemathError,
+    StagnationError,
+    TimeBudgetError,
+    UnsupportedFormError,
+)
+from .core.ir import E, Expr, M, Matrix, V, symbols
+from .core.result import (
+    SOLVE_STATUSES,
+    QuadratureResult,
+    SolveResult,
+    SolveStatus,
+)
+from .engine import linalg, numerics, ode, symbolic
+from .engine.numerics import (
+    gradient,
+    hessian,
+    integrate_num,
+    jacobian,
+    minimize,
+    minimize_nd,
+    root_find,
+    root_find_nd,
+)
+from .engine.ode import (
+    DenseSolution,
+    DenseSystemSolution,
+    EventSolution,
+    EventSystemSolution,
+    dsolve,
+    solve_ode_adaptive,
+    solve_ode_dense,
+    solve_ode_events,
+    solve_ode_num,
+    solve_ode_stiff,
+    solve_ode_stiff_adaptive,
+    solve_ode_system_dense,
+    solve_ode_system_events,
+    solve_ode_system_num,
+    solve_ode_system_stiff,
+    solve_ode_system_stiff_adaptive,
+)
+from .engine.symbolic import limit, series, summation
+from .frontend.parser import parse
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "E",
+    "Expr",
+    "M",
+    "V",
+    "Matrix",
+    "symbols",
+    "parse",
+    "PycodemathError",
+    "ParseError",
+    "DomainError",
+    "DivergenceError",
+    "StagnationError",
+    "NonConvergenceError",
+    "NotAMinimumError",
+    "BudgetExhaustedError",
+    "TimeBudgetError",
+    "NoClosedFormError",
+    "UnsupportedFormError",
+    "ROUTES",
+    "NUMERIC_ROUTES",
+    "time_budget",
+    "DEFAULT_TIME_BUDGET",
+    "SolveResult",
+    "QuadratureResult",
+    "SolveStatus",
+    "SOLVE_STATUSES",
+    "symbolic",
+    "linalg",
+    "numerics",
+    "ode",
+    "generate",
+    "generate_system",
+    "generate_ode",
+    "generate_ode_adaptive",
+    "generate_ode_dense",
+    "CodeArtifact",
+    "limit",
+    "series",
+    "summation",
+    "gradient",
+    "jacobian",
+    "hessian",
+    # The five functions that RETURN the types just above. Before module 7 only the
+    # ``_nd`` pair was exported, so ``from pycodemath import SolveResult`` worked
+    # while ``from pycodemath import root_find`` — the very call that produces one —
+    # did not. Same module, same contract, same @overload: the split was an accident.
+    "root_find",
+    "minimize",
+    "root_find_nd",
+    "minimize_nd",
+    "integrate_num",
+    "dsolve",
+    "solve_ode_num",
+    "solve_ode_stiff",
+    "solve_ode_stiff_adaptive",
+    "solve_ode_adaptive",
+    "solve_ode_dense",
+    "DenseSolution",
+    "solve_ode_events",
+    "EventSolution",
+    "solve_ode_system_num",
+    "solve_ode_system_stiff",
+    "solve_ode_system_stiff_adaptive",
+    "solve_ode_system_dense",
+    "DenseSystemSolution",
+    "solve_ode_system_events",
+    "EventSystemSolution",
+    "__version__",
+]

{pycodemath-0.2.0 → pycodemath-0.3.0}/pycodemath/__main__.py

@@ -1,10 +1,10 @@
-"""Entry point: ``python -m pycodemath`` — REPL or one-shot from arguments.
-
-Forcing UTF-8 for the Windows console is done by ``run()`` (shared with the
-``pycodemath`` console script).
-"""
-
-from .cli.repl import run
-
-if __name__ == "__main__":
-    run()
+"""Entry point: ``python -m pycodemath`` — REPL or one-shot from arguments.
+
+Forcing UTF-8 for the Windows console is done by ``run()`` (shared with the
+``pycodemath`` console script).
+"""
+
+from .cli.repl import run
+
+if __name__ == "__main__":
+    run()

{pycodemath-0.2.0 → pycodemath-0.3.0}/pycodemath/bench/benchmark.py

@@ -1,61 +1,61 @@
-"""Benchmark — proof of the thesis: code with CSE beats naive Python.
-
-We take an expression with heavily repeating subexpressions, generate two
-versions (with CSE and without), then measure time over a vectorized NumPy
-array. The CSE version computes the repeats once — it should be measurably
-faster.
-"""
-
-from __future__ import annotations
-
-import sys
-import time
-
-import numpy as np
-
-from ..codegen.pipeline import generate
-from ..frontend.parser import parse
-
-# Subexpression (sin(x)+cos(x))**? repeated many times — ideal for CSE.
-DEMO = "(sin(x)+cos(x))**2 + (sin(x)+cos(x))**3 + (sin(x)+cos(x))**4 + exp(sin(x)+cos(x))"
-
-
-def _time(func, x, repeats: int = 200) -> float:
-    best = float("inf")
-    for _ in range(repeats):
-        t0 = time.perf_counter()
-        func(x)
-        best = min(best, time.perf_counter() - t0)
-    return best
-
-
-def main() -> None:
-    for stream in (sys.stdout, sys.stderr):
-        if hasattr(stream, "reconfigure"):
-            stream.reconfigure(encoding="utf-8")
-    expr = parse(DEMO)
-    naive = generate(expr, func_name="naive", simplify=False, use_cse=False)
-    optimized = generate(expr, func_name="opt", simplify=False, use_cse=True)
-
-    x = np.linspace(0.1, 10.0, 200_000)
-
-    # sanity: both give the same result
-    assert np.allclose(naive(x), optimized(x)), "results differ!"
-
-    t_naive = _time(naive.func, x)
-    t_opt = _time(optimized.func, x)
-
-    print("Demo expression:")
-    print(f"  {DEMO}\n")
-    print("Naive code (without CSE):")
-    print("  " + naive.source.replace("\n", "\n  ") + "\n")
-    print("Optimized code (CSE):")
-    print("  " + optimized.source.replace("\n", "\n  ") + "\n")
-    print(f"naive time      : {t_naive * 1e3:.3f} ms")
-    print(f"CSE time        : {t_opt * 1e3:.3f} ms")
-    if t_opt > 0:
-        print(f"speedup         : {t_naive / t_opt:.2f}x")
-
-
-if __name__ == "__main__":
-    main()
+"""Benchmark — proof of the thesis: code with CSE beats naive Python.
+
+We take an expression with heavily repeating subexpressions, generate two
+versions (with CSE and without), then measure time over a vectorized NumPy
+array. The CSE version computes the repeats once — it should be measurably
+faster.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+
+import numpy as np
+
+from ..codegen.pipeline import generate
+from ..frontend.parser import parse
+
+# Subexpression (sin(x)+cos(x))**? repeated many times — ideal for CSE.
+DEMO = "(sin(x)+cos(x))**2 + (sin(x)+cos(x))**3 + (sin(x)+cos(x))**4 + exp(sin(x)+cos(x))"
+
+
+def _time(func, x, repeats: int = 200) -> float:
+    best = float("inf")
+    for _ in range(repeats):
+        t0 = time.perf_counter()
+        func(x)
+        best = min(best, time.perf_counter() - t0)
+    return best
+
+
+def main() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    expr = parse(DEMO)
+    naive = generate(expr, func_name="naive", simplify=False, use_cse=False)
+    optimized = generate(expr, func_name="opt", simplify=False, use_cse=True)
+
+    x = np.linspace(0.1, 10.0, 200_000)
+
+    # sanity: both give the same result
+    assert np.allclose(naive(x), optimized(x)), "results differ!"
+
+    t_naive = _time(naive.func, x)
+    t_opt = _time(optimized.func, x)
+
+    print("Demo expression:")
+    print(f"  {DEMO}\n")
+    print("Naive code (without CSE):")
+    print("  " + naive.source.replace("\n", "\n  ") + "\n")
+    print("Optimized code (CSE):")
+    print("  " + optimized.source.replace("\n", "\n  ") + "\n")
+    print(f"naive time      : {t_naive * 1e3:.3f} ms")
+    print(f"CSE time        : {t_opt * 1e3:.3f} ms")
+    if t_opt > 0:
+        print(f"speedup         : {t_naive / t_opt:.2f}x")
+
+
+if __name__ == "__main__":
+    main()