CipherExplain

1. Add to your workflow

Create .github/workflows/fhe-check.yml in your repo:

name: FHE Precision Test
on: [push, pull_request]

jobs:
  fhe-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run FHE Oracle
        run: |
          curl -X POST \
            https://cipherexplain.vaultbytes.com/oracle/run \
            -H "X-API-Key: ${{ secrets.VAULTBYTES_API_KEY }}" \
            -F "circuit=@src/my_circuit.py" \
            --fail-with-body
          # Exit 0 = PASS, Exit 1 = BUG FOUND (see report)

Add VAULTBYTES_API_KEY to your repo secrets (Settings → Secrets → New repository secret). The pipeline fails automatically if a precision bug is found — no code changes needed beyond adding this step.

2. Create your circuit file

Three required exports in src/my_circuit.py:

INPUT_DIM = 10  # how many input features your model takes

def plaintext(x):
    # Your original (unencrypted) model
    # This is the ground truth
    return float(model.predict(x))

def fhe_simulated(x):
    # Your FHE-compiled model
    # This is what we're testing
    return float(fhe_model.run(x))

# The Oracle calls both with the same inputs
# and finds the worst-case difference between them.

PASS = outputs agree everywhere → exit 0. FAIL = divergence found → exit 1 + PDF report with the exact input that triggered the bug, the size of the error, and a sensitivity map showing which features caused it.

Python

Load the demo model, then call /explain_raw with raw (unscaled) values:

import requests

BASE = "https://cipherexplain.vaultbytes.com"
HDR  = {"X-API-Key": "vb_..."}

# One-time: load the built-in demo credit model
requests.post(f"{BASE}/startup", headers=HDR)

# Send the raw feature values for one person
r = requests.post(f"{BASE}/explain_raw", headers=HDR,
  json={
    "model_id": "credit_model",
    "features": [38,  13,    0,       0,      40 ]
    #             ↑    ↑      ↑        ↑        ↑
    #            age  edu  marital  occup  hrs/week
  }
)
data = r.json()

# What comes back:
# data["prediction"]    → 0.74   (74% probability — your app maps to a label)
# data["base_rate"]     → 0.50   (average across all cases — the neutral baseline)
# data["shap_values"]   → [0.12, -0.31, 0.05, 0.03, 0.09]
# data["feature_names"] → ["age", "education-num", "marital", "occup", "hours"]
#
# Reading the SHAP values:
#   education-num: -0.31 → biggest factor, pushed prediction DOWN
#   age:            0.12 → pushed it up
#   hours/week:     0.09 → positive signal
#   occupation:     0.05 → small positive
#   marital:        0.03 → almost no effect

/explain_raw auto-scales your values using the model's built-in scaler. Use /explain only if you have already scaled the features yourself.

curl

curl -s -X POST \
  https://cipherexplain.vaultbytes.com/explain_raw \
  -H "X-API-Key: vb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "credit_model",
    "features": [38, 13, 0, 0, 40]
  }' | python3 -m json.tool

All endpoints

POST /startup              → load demo credit model
GET  /models               → list your registered models
POST /models/register      → register your own model
DELETE /models/{id}        → remove a model
POST /explain              → SHAP (pre-scaled features)
POST /explain_raw          → SHAP (raw values, auto-scaled)
POST /report               → generate PDF audit report
POST /keys/rotate          → rotate your API key
GET  /usage                → quota used this month
GET  /health               → status (no key needed)

All endpoints except /health and /signup/* require X-API-Key. Returns JSON. 401 = missing key, 403 = invalid key, 429 = quota exceeded.
Full interactive docs: cipherexplain.vaultbytes.com/docs

Register any linear classifier

Your model and data stay local. Only trained weights (numbers) are sent — no training data, no pickle files, no arbitrary code.

pip install cipherexplain

from cipherexplain_sdk import CipherExplainClient, extract_spec, from_weights

# --- sklearn (LogisticRegression, LinearSVC) ---
from sklearn.linear_model import LogisticRegression
spec = extract_spec(LogisticRegression().fit(X_s, y),
                    "my_lr", feature_names, scaler=scaler)

# --- PyTorch nn.Linear ---
import torch.nn as nn
spec = extract_spec(nn.Linear(n, 1), "my_pt", feature_names)

# --- Any other framework (TF, JAX, statsmodels, R, ...) ---
# Export coef/intercept as arrays, then:
spec = from_weights(coef, intercept, "my_model",
                    feature_names, classes=[0, 1])

# Register and explain
client = CipherExplainClient(api_key="vb_...")
client.register(spec)
result = client.explain_raw("my_model", x_raw)
print(result["shap_values"])

Supported: any linear classifier (logistic regression, linear SVM, linear layer). Non-linear models (trees, MLPs) are not supported — only linear weights can be serialised safely without pickle.

Model slots & key rotation

Each API key has a model slot quota by tier:

• Free — 1 model
• Developer — 10 models
• Enterprise — no limit

Delete a model to free its slot:

client.delete("my_model")

Rotate your API key at any time — all registered models move automatically:

result = client.rotate_key()
# result["new_key"] → "vb_..."
# Your old key stops working immediately.

Models survive key rotation. No re-registration needed. Store the new key before it leaves your terminal.