certsf 0.1.0a1__tar.gz

certsf-0.1.0a1/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

certsf-0.1.0a1/.github/workflows/release-checks.yml

@@ -0,0 +1,43 @@
+name: release-checks
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Check package metadata
+        run: python -m twine check dist/*
+      - name: Install built wheel
+        run: python -m pip install dist/*.whl
+      - name: Import installed package
+        run: python -c "import certsf; print(certsf.__all__)"
+
+  lint-type:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install static-analysis tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+          python -m pip install pyright
+      - name: Run ruff
+        run: ruff check .
+      - name: Run pyright
+        run: pyright src --pythonpath "$(which python)"

certsf-0.1.0a1/.github/workflows/tests.yml

@@ -0,0 +1,70 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  package-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build backend
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+
+  lint-type:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package and dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Run ruff
+        run: python -m ruff check src tests examples
+      - name: Run mypy
+        run: python -m mypy
+
+  pytest-certified:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test,certified]"
+      - name: Run tests
+        run: python -m pytest
+
+  pytest-base:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+      - name: Run tests
+        run: python -m pytest

certsf-0.1.0a1/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+.venv/
+venv/
+env/
+
+build/
+dist/
+*.egg-info/
+
+.DS_Store
+Thumbs.db

certsf-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0-alpha.1 - 2026-05-07
+
+- Added special-function wrappers for gamma, Airy, Bessel, and parabolic-cylinder families.
+- Added SciPy fast mode, mpmath high-precision mode, and optional python-flint certified mode.
+- Added structured `SFResult` diagnostics, MCP wrappers, CI, and certification documentation.
+- Hardened dispatcher v2 with an explicit backend method registry and API/MCP coverage checks.

certsf-0.1.0a1/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If you use certsf in research, please cite it using this metadata."
+title: "certsf: Certified special-function wrappers with explicit diagnostics"
+version: 0.1.0-alpha.1
+date-released: 2026-05-07
+authors:
+  - family-names: Lee
+    given-names: Yutian
+repository-code: "https://github.com/yutianlee/certsf"
+license: MIT

certsf-0.1.0a1/LICENSE

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

certsf-0.1.0a1/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: certsf
+Version: 0.1.0a1
+Summary: Certified special-function wrappers with explicit diagnostics.
+Project-URL: Homepage, https://github.com/yutianlee/certsf
+Project-URL: Repository, https://github.com/yutianlee/certsf
+Project-URL: Issues, https://github.com/yutianlee/certsf/issues
+Author: Yutian Lee
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arb,interval-arithmetic,mpmath,scientific-computing,special-functions,validated-numerics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: mpmath>=1.3
+Requires-Dist: scipy>=1.10
+Provides-Extra: certified
+Requires-Dist: python-flint>=0.6; extra == 'certified'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mcp>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: python-flint>=0.6; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# certsf
+
+`certsf` provides special-function wrappers with explicit diagnostics and, where
+available, rigorous Arb ball enclosures through `python-flint`.
+
+The public API is intentionally small: every function returns an `SFResult`
+object with the computed value, backend metadata, certification status, optional
+error bounds, and diagnostics explaining how the result was produced.
+
+The certification scope lives in [`docs/certification.md`](docs/certification.md);
+the scope-by-scope audit lives in
+[`docs/certification_audit.md`](docs/certification_audit.md);
+the 0.1.0 certified support matrix lives in
+[`docs/certified_scope_0_1_0.md`](docs/certified_scope_0_1_0.md), and the formula
+audit trail lives in [`docs/formula_audit.md`](docs/formula_audit.md).
+
+## Installation
+
+For local development:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+For runtime use without optional MCP tooling:
+
+```powershell
+python -m pip install -e ".[certified]"
+```
+
+The base package depends on `scipy` and `mpmath`. Certified mode additionally
+requires `python-flint`.
+
+## Quick Start
+
+```python
+from certsf import gamma, besselj, pcfu
+
+g = gamma("3.2", dps=50, mode="certified")
+j = besselj("2.5", "4.0+1.25j", dps=60, mode="certified")
+u = pcfu("2.5", "1.25", dps=60, mode="certified")
+
+print(g.value)
+print(g.abs_error_bound)
+print(g.certified)
+print(g.backend)
+print(g.diagnostics)
+```
+
+For a plain numerical value, use `mode="fast"` or `mode="high_precision"`:
+
+```python
+from certsf import airy
+
+result = airy("1.0", dps=80, mode="high_precision")
+print(result.value)
+```
+
+## Result Object
+
+Every wrapper returns an `SFResult` with these fields:
+
+- `value`: string value, or a JSON string for multi-component results.
+- `abs_error_bound`: rigorous absolute error bound when certified.
+- `rel_error_bound`: rigorous relative error bound when available.
+- `certified`: `True` only when a rigorous enclosure was produced.
+- `function`: canonical function name.
+- `method`: implementation method, such as `scipy.special`, `mpmath`, or
+  `arb_ball`.
+- `backend`: backend package name.
+- `requested_dps`: requested decimal precision.
+- `working_dps`: internal decimal precision estimate.
+- `diagnostics`: structured details about mode, domain, formula, and scope.
+
+Unsupported certified domains return a clean non-certified result with
+`value=""`, `certified=False`, and an explanatory diagnostics error. They do not
+silently fall back to mpmath and call the value certified.
+
+Certified successes also expose `diagnostics["certificate_level"]`,
+`diagnostics["audit_status"]`, and `diagnostics["certification_claim"]`, so
+callers can distinguish direct Arb primitive wrappers from formula-backed
+experimental claims.
+
+## Choosing a Mode
+
+- `mode="fast"` uses `scipy.special`; it is quick and non-certified.
+- `mode="high_precision"` uses `mpmath`; it supports higher precision and
+  complex arguments, but is still non-certified.
+- `mode="certified"` uses `python-flint` / Arb when a validated enclosure path
+  exists.
+- `mode="auto"` chooses certified mode when `certify=True`, otherwise fast mode
+  for `dps <= 15` and high-precision mode for larger `dps` requests.
+
+Fast mode is double precision. If you request more than 15 digits while forcing
+`mode="fast"`, the result reports `working_dps=16` and includes a diagnostic
+warning that the requested digits are not guaranteed.
+
+Use `mode="certified"` when the error bound matters. Use `high_precision` when
+you need more digits but not a rigorous certificate.
+
+The dispatcher uses an explicit `MethodSpec` registry for every concrete mode.
+Each registered method records its backend, callable, certification intent,
+domain note, and certificate scope. Adding a public wrapper requires registering
+its SciPy, mpmath, and Arb methods together; tests verify the registry, public
+API, and MCP tool list stay in sync.
+
+## Supported Functions
+
+The 0.1.0 alpha public certified surface is frozen. No additional public
+special-function wrappers are planned before 0.1.0; the release work is focused
+on audit, validation, packaging, and documentation.
+
+| Area | Release status |
+| --- | --- |
+| `gamma`, `loggamma`, `rgamma` | alpha-certified, direct Arb primitive |
+| `airy`, `ai`, `bi` | alpha-certified, direct Arb primitive |
+| `besselj`, `bessely`, `besseli`, `besselk` | alpha-certified where direct Arb primitive works; real-valued order only |
+| `pcfd`, `pcfu`, `pcfv`, `pcfw`, `pbdv` | experimental certified formula layer |
+| MCP server | experimental tool interface |
+| Custom Taylor/asymptotic methods | not yet |
+
+```python
+from certsf import (
+    gamma,
+    loggamma,
+    rgamma,
+    airy,
+    ai,
+    bi,
+    besselj,
+    bessely,
+    besseli,
+    besselk,
+    pbdv,
+    pcfd,
+    pcfu,
+    pcfv,
+    pcfw,
+)
+```
+
+### Gamma Family
+
+- `gamma(z)`
+- `loggamma(z)`, using the principal branch
+- `rgamma(z) = 1 / gamma(z)`
+
+`rgamma` is the safest wrapper near non-positive integer gamma poles. In
+certified mode, `rgamma` returns a rigorous zero at poles, while `gamma` and
+`loggamma` return clean non-certified failures when the requested value is not
+finite.
+
+### Airy Family
+
+- `airy(z)` returns Ai, Ai', Bi, and Bi' in one JSON payload.
+- `ai(z, derivative=0)` and `ai(z, derivative=1)`.
+- `bi(z, derivative=0)` and `bi(z, derivative=1)`.
+
+Certified Airy wrappers use Arb ball arithmetic and report component-level
+absolute and relative error bounds.
+
+### Bessel Family
+
+- `besselj(v, z)` for \(J_v(z)\)
+- `bessely(v, z)` for \(Y_v(z)\)
+- `besseli(v, z)` for \(I_v(z)\)
+- `besselk(v, z)` for \(K_v(z)\)
+
+Certified Bessel wrappers support real-valued order and real or complex
+arguments. Complex order is outside the certified scope and returns a clean
+non-certified failure.
+
+### Parabolic-Cylinder Family
+
+- `pbdv(v, x)` returns \(D_v(x)\) and \(D_v'(x)\) in one JSON payload.
+- `pcfd(v, z)` returns \(D_v(z)\).
+- `pcfu(a, z)` returns \(U(a,z)\).
+- `pcfv(a, z)` returns \(V(a,z)\).
+- `pcfw(a, x)` returns \(W(a,x)\).
+
+Certified `pcfu`, `pcfd`, `pbdv`, and `pcfv` support real parameters and real
+or complex arguments. Certified `pcfw` currently supports real parameters and
+real arguments; complex arguments return a clean non-certified failure until a
+validated complex-domain target is selected.
+
+The parabolic-cylinder family is an experimental certified formula layer: Arb
+encloses the implemented documented formula, while formula/domain audit remains
+visible before broadening the claim.
+
+## Multi-Component Values
+
+Functions such as `airy` and `pbdv` keep backward-compatible JSON strings in
+`SFResult.value`, and provide helpers for Python callers:
+
+```python
+from certsf import pbdv
+
+result = pbdv("2.5", "1.25", dps=60, mode="certified")
+values = result.value_as_dict()
+bounds = result.abs_error_bound_as_dict()
+
+print(values["value"])
+print(values["derivative"])
+print(bounds["value"])
+print(bounds["derivative"])
+print(result.component("value"))
+```
+
+## MCP Wrapper
+
+`certsf.mcp_server` exposes thin MCP-facing wrappers around the same public API.
+MCP payloads decode multi-component values and bounds as nested JSON objects
+instead of JSON-encoded strings.
+Install the optional MCP dependency before running the server:
+
+```powershell
+python -m pip install -e ".[mcp,certified]"
+python -m certsf.mcp_server
+```
+
+## Development
+
+Run the test suite with:
+
+```powershell
+python -m pytest
+```
+
+The tests exercise the SciPy, mpmath, and Arb-backed paths when the optional
+dependencies are installed.
+
+The repository also includes:
+
+- `docs/release_checklist.md` for prerelease/release verification.
+- `docs/certification_audit.md` for scope-level certification evidence and
+  remaining audit gates.
+- `docs/audit/` for family-level certification checklists.
+- `docs/certified_scope_0_1_0.md` for the frozen 0.1.0 certified support
+  matrix.
+- `docs/release-0.1.0.md` for alpha release notes and example commands.
+- `examples/basic_usage.py` for a short end-to-end usage example.
+- `examples/certified_vs_high_precision.py` for a compact comparison of
+  high-precision and certified result diagnostics.
+- `examples/gamma_certified.py`, `examples/airy_components.py`,
+  `examples/bessel_complex.py`, `examples/pcf_experimental.py`, and
+  `examples/mcp_payload.py` for payload-first release examples.
+- `benchmarks/bench_gamma.py`, `benchmarks/bench_airy.py`,
+  `benchmarks/bench_bessel.py`, and `benchmarks/bench_pcf.py` for lightweight
+  JSON-lines timing smoke benchmarks.