$ pip install fhe-oracle
Adversarial precision testing for Fully Homomorphic Encryption. Finds CKKS, BGV, BFV, and TFHE bugs that random testing misses. Open source, free forever, CMA-ES search with noise-aware fitness. Drop into CI and fail the build when your encrypted circuit diverges from its plaintext twin.
FHE precision bugs are input-localised. A CKKS circuit that passes 99,999 random inputs can still return garbage on the 100,000th.
Homomorphic schemes (CKKS, BGV, BFV) accumulate noise input by input. The inputs that trigger failure sit in narrow regions of the input space — regions that scale with multiplicative depth and the magnitude of intermediate ciphertexts. Those regions are vanishingly unlikely to be hit by uniform random sampling.
Result: your test suite passes, your production circuit silently returns catastrophically wrong answers on specific feature vectors. No existing FHE toolchain has a CI/CD gate for this.
Random testing wastes evaluations in safe parts of the input space. An adversarial optimiser — CMA-ES guided by a noise-budget-aware fitness — spends its budget climbing toward the failure region and finds bugs orders of magnitude larger than random sampling at the same wall-clock budget.
On the CKKS logistic regression defect benchmark (CKKS logistic regression with polynomial sigmoid defect), FHE Oracle finds divergence 4,259× larger than random at a 500-evaluation budget.
One line. Python 3.9+. AGPL-3.0. No API key, no account, no telemetry.
pip install fhe-oracle
Pure-divergence mode — no native FHE library required. Works in any CI environment that can install numpy and cma.
pip install 'fhe-oracle[tenseal]' # or bring your own adapter for # OpenFHE · Concrete ML · SEAL
The [tenseal] extra turns on noise-guided search for CKKS. OpenFHE, Concrete ML, and SEAL adapters are shipped pluggable — wire up your compiled circuit.
Two Python functions — your plaintext model and its FHE-compiled version. The Oracle finds where they disagree.
import numpy as np
from fhe_oracle import FHEOracle
def plaintext_fn(x):
return float(np.sum(np.asarray(x) ** 2))
def fhe_fn(x):
# Stand-in for your FHE-compiled predict function.
# Here: noise scales with input norm^2 (CKKS depth-noise pattern),
# with a hot zone that inflates error 100x when |x|^2 > 8.
v = float(np.sum(np.asarray(x) ** 2))
base = 1e-5 * v
amp = 100.0 if v > 8.0 else 1.0
return plaintext_fn(x) + base * amp
oracle = FHEOracle(
plaintext_fn=plaintext_fn,
fhe_fn=fhe_fn,
input_dim=4,
input_bounds=[(-3.0, 3.0)] * 4,
seed=0,
)
result = oracle.run(n_trials=300, threshold=1e-3)
print(result.verdict) # "FAIL"
print(result.max_error) # ~3.6e-2
print(result.worst_input) # ~[3.0, 3.0, 3.0, -3.0]
Adversarial CMA-ES over the input domain, guided by a noise-aware fitness that combines divergence with ciphertext-level signals.
Multi-objective CMA-ES fitness maximises divergence, noise budget consumption, and multiplication-depth utilisation. Produces a sensitivity map identifying which input dimensions drive divergence.
Every run returns a structured OracleResult:
Live runs from the repo at a 500-evaluation budget, deterministic seed 42. Each benchmark takes under one second on a 2020-era laptop.
| Circuit | Dim | Random max error | Oracle max error | Ratio | |----------------------------------------|-----|------------------|------------------|-----------| | Logistic regression (patent reference) | 5 | 3.5e-4 | 1.50 | 4,259× | | Logistic regression (input-amplified) | 8 | 2.7e-1 | 6.8e-1 | 2.5× | | Polynomial (depth 4) | 6 | 1.7e-2 | 1.9e-2 | 1.1× | | Dense + Chebyshev sigmoid | 10 | — | 1.0e-1 | — |
All opt-in. Backward-compatible with v0.3.x. Enable individually or through AutoOracle.
Injects diverse candidates (corner / uniform / best-neighbour) into the CMA-ES population every N generations. Prevents the covariance collapse that strands vanilla CMA-ES on plateau landscapes.
FHEOracle(..., diversity_injection=True,
inject_every=5, inject_count=3)
Early-stops on a definitive FAIL, auto-extends when divergence is still climbing at budget exhaustion, and switches to uniform random when CMA-ES step size collapses on a plateau.
FHEOracle(..., adaptive=True) # configure via AdaptiveConfig
Wraps vector-valued plaintext/FHE pairs in a MultiOutputFitness that targets decision-altering failures (argmax flips, near-margin inputs) on top of max-absolute error.
FHEOracle(..., multi_output=True,
multi_output_mode="combined")
# MultiOutputFitness.detailed_report(x)
Runs a 50-eval probe that classifies the divergence landscape (FULL_DOMAIN_SATURATION, PLATEAU_THEN_CLIFF, PREACTIVATION_DOMINATED, STANDARD) and dispatches to the best search strategy automatically.
from fhe_oracle import AutoOracle
AutoOracle(..., adaptive=True,
diversity_injection=True)
random_floor=0.3 reserves budget for uniform sampling, then warm-starts CMA-ES at the best random point.restarts=N, bipop=True for multi-basin landscapes.separable=True for axis-aligned high-dimensional search.PreactivationOracle(W, b, ...) collapses d=784 affine front-ends to a rank-k subproblem.d >> 100.per_op_trace(x, plain, fhe) and TracingTenSEALFn localise where error accumulates in a CKKS circuit.Drop two files into your repo and fail the build when your FHE circuit diverges from its plaintext twin.
oracle_check.pyimport os
from fhe_oracle import FHEOracle
from my_model import plaintext_fn, fhe_fn
oracle = FHEOracle(
plaintext_fn=plaintext_fn,
fhe_fn=fhe_fn,
input_dim=10,
input_bounds=[(-3.0, 3.0)] * 10,
)
result = oracle.run(
n_trials=int(os.environ.get("ORACLE_N_TRIALS", "500")),
threshold=float(os.environ.get("ORACLE_THRESHOLD", "0.01")),
)
print(result)
raise SystemExit(0 if result.verdict == "PASS" else 1)
.github/workflows/fhe-precision.ymlname: FHE Precision Test
on: [push, pull_request]
jobs:
fhe-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: "3.11" }
- run: pip install fhe-oracle
- run: python oracle_check.py
env:
ORACLE_THRESHOLD: "0.01"
ORACLE_N_TRIALS: "500"
Pluggable noise models. Works with every major open FHE stack.
CKKS, BGV, BFV. Wire your compiled circuit's Eval call into fhe_fn and the noise-guided fitness activates.
Swap predict_proba(x, fhe="execute") in for the FHE function. Works with TFHE circuits out of the box.
CKKS and BFV. Bring your encoder / evaluator; the oracle handles the search layer.
pip install 'fhe-oracle[tenseal]' — first-class CKKS with noise-budget-aware search.
Shipped on PyPI. Reverse chronological.
AutoOracle probe, experimental SubspaceOracle.Free for open-source and research. Commercial licence available.
The source code on PyPI and GitHub is licensed under the GNU Affero General Public License v3.0. Use it freely in open-source projects, research, and internal CI pipelines. If you run it as a network service, the AGPL copyleft applies to your deployment.
Need a permissive commercial licence? Talk to us — we offer commercial / OEM licences for FHE compiler vendors and enterprise integrators.
A PCT patent application covering the adversarial noise-guided differential testing method is pending:
System and Method for Adversarial Noise-Guided Differential Testing of Fully Homomorphic Encryption Programs
Priority date April 7, 2026. PCT coverage spans 150+ countries. The AGPL-3.0 grant on this package includes a patent licence for non-commercial and open-source use in compliance with the licence.
FHE Oracle is the free, open-source precision-testing engine. If you also need hosted CI, audit reports, encrypted SHAP explanations, or a commercial licence — see CipherExplain.
Self-host. Run in your own CI. Patch and fork as you like, subject to AGPL-3.0. Community support via GitHub issues.
Hosted API, signed PDF audit reports for EU AI Act compliance, encrypted SHAP explanations (CKKS), custom model registration, key rotation, SLA, DPA, on-prem — and a commercial (non-AGPL) licence for the Oracle.
Bug reports and feature requests on GitHub. Commercial licence enquiries and partnership discussions by email.
FHE Oracle is maintained by VaultBytes. Enterprise licensing, NDA evaluations, and custom adapter development available — b@vaultbytes.com.