CipherExplain

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
GET  /models/{id}/versions     → list model versions (audit)
GET  /models/{id}/commitment   → KZG commitment for FreiKZG verify
DELETE /models/{id}            → remove a model
POST /explain                  → SHAP (pre-scaled features)
POST /explain_raw              → SHAP (raw values, auto-scaled)
POST /explain/batch            → async batch — webhook delivery
GET  /explain/batch/{job_id}   → poll batch job status
POST /report                   → generate PDF audit report
POST /keys/rotate              → rotate your API key
GET  /usage                    → quota used this month
GET  /usage/dp                 → remaining DP privacy budget (ε)
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 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
client = CipherExplainClient(api_key="vb_...")

# --- sklearn Pipeline auto-unwrap (embedded scaler stripped) ---
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression
pipe = Pipeline([("scaler", StandardScaler()),
                 ("clf",    LogisticRegression())]).fit(X, y)
client.register_pipeline("my_model", pipe, feature_names, X_train=X)

# --- XGBoost binary classifier ---
import xgboost as xgb
booster = xgb.XGBClassifier().fit(X, y)
client.register_xgboost("my_xgb", booster, feature_names)

# --- LightGBM binary classifier ---
import lightgbm as lgb
gbm = lgb.LGBMClassifier().fit(X, y)
client.register_lightgbm("my_lgb", gbm, feature_names)

# --- MLP (ReLU) — CKKS-evaluated ---
from sklearn.neural_network import MLPClassifier
mlp = MLPClassifier(hidden_layer_sizes=(16, 8)).fit(X, y)
client.register_mlp("my_mlp", mlp, feature_names, X_train=X)

# --- Any other framework — raw weights ---
from cipherexplain_sdk import from_weights
spec = from_weights(coef, intercept, "my_linear",
                    feature_names, classes=[0, 1])
client.register(spec)

# Explain with full FHE + optional DP noise
result = client.explain_raw("my_model", x_raw,
                            fhe_mode="execute", apply_dp=True)
print(result["shap_values"])
print(result["model_version_id"])   # audit pin
print(result["fhe_mode_used"])       # "ckks_engine"

High-level registration helpers: register_pipeline(), register_xgboost(), register_lightgbm(), register_mlp(), register_catboost(). Raw-weights adapter: from_weights() + client.register(spec). Binary classification only.

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.