Implicant SDK

Python client for the Implicant FHE inference platform. Encrypts one row locally under BGV, sends the ciphertext to the platform for homomorphic evaluation, and decrypts the result. The server never sees plaintext; the secret key never leaves the process.

The classifier head runs server-side under FHE (Variant B): the platform returns one ciphertext with the class scores packed contiguously, which the client decrypts (unsigned) and decodes with decode_class_scores before threshold/argmax. W / b never reach the client.

Pure Python — all crypto comes from implicant-fhe (helut.client). Architecture and byte contracts: docs/architecture.md.

Install

pip install implicant

Pulls implicant-fhe (the helut crypto wheel) from PyPI automatically. Wheels ship for CPython 3.10–3.14 on macOS-arm64 and manylinux x86_64 only. On any other target — Windows, Linux aarch64, macOS x86_64 — there is no wheel and no source fallback, so pip stops with No matching distribution found for implicant-fhe.

Developers

python3.13 -m venv .venv313
.venv313/bin/pip install -e ".[dev]"
.venv313/bin/pytest tests/ -v      # ~550 tests (real BGV keygen; slow)

To pin an unreleased implicant-fhe build, stage its wheel in ./wheels/ and add --find-links wheels/; the published versions resolve from PyPI without it.

Running an inference (CLI)

The implicant CLI is the client-side workflow: configure once, then run encrypted predictions. Everything stays local except the ciphertext and the public keys — the secret key never leaves your machine.

This release is demo-only: every predict needs --demo (or IMPLICANT_DEMO=1 in the environment) and runs on the bundled demo keypair — see Demo mode for what that implies. Without the flag, predict exits with an explanatory message.

1. Point the client at the platform

implicant init --api-url https://api.implicant.example

Writes ~/.implicant/config.toml. Run implicant status to confirm the configured api_url and list any locally cached keys.

2. Set your API token

The bearer token is read from the environment, never stored on disk:

export IMPLICANT_API_KEY="imp_..."

3. Discover the available models

The SDK ships a hand-maintained registry of the models servable on the platform (there is no server-side listing endpoint yet):

$ implicant models list
credit        Predicts whether a borrower will default on a loan
bankfraud     Predicts whether a bank account application is fraudulent
heartdisease  Predicts whether a patient has heart disease
cancer        Predicts whether a breast tumor is malignant or benign
diabetes      Predicts whether a patient will be readmitted within 30 days

Try one:           implicant predict --model <slug> --sample --demo
Editable example:  implicant models sample <slug> --out row.json
Then:              implicant predict --model <slug> --input row.json --demo

The listed slug is the --model value for predict.

4. Prepare the input row

One row of raw feature values, as a JSON object (or a single-row CSV). The keys are the feature names the model expects. Each known model ships a bundled example row — the fastest way to get a correct starting point:

implicant models sample diabetes --out row.json   # or no --out to print to stdout

{
  "age": "[80-90)",
  "medical_specialty": "InternalMedicine",
  "discharge_disposition_id": 6.0,
  "time_in_hospital": 4.0,
  "num_lab_procedures": 56.0,
  "num_medications": 16.0,
  "number_emergency": 1.0986122886681098,
  "number_inpatient": 2.3978952727983707,
  "number_diagnoses": 9.0
}

Edit the values by hand to test different inputs, then feed the file to predict. Keep categorical values as quoted strings ("[80-90)" above) — they are matched textually against the model's fitted levels. (--out refuses to overwrite an existing file unless you pass --force.)

5. Predict

implicant predict --model diabetes --input row.json --demo

Or skip the file entirely and run on the bundled example row:

implicant predict --model diabetes --sample --demo

This fetches the model manifest, generates (or reloads) your keys, uploads the public keys on first use, encrypts the row locally, sends the ciphertext, then decrypts and decodes the returned class scores. Progress streams to stderr (with a spinner on the current step in a terminal) and the decision lands on stdout:

✓ Fetching model configuration
✓ Preparing encryption keys
✓ Encrypting input data
✓ Evaluating on the server (encrypted)
✓ Decrypting server response
Final decision: readmitted

Add --json for the machine-readable result instead of the decision line (progress stays on stderr, so piping stdout to jq is safe):

{
  "key_id": "bgv-n16384-L8-5f657f27f77c",
  "label_index": 1,
  "label": "readmitted",
  "scores": [2028]
}

Add --no-persist-key to use an ephemeral secret key for a single run (nothing written to disk; keys are regenerated and re-uploaded next time).

Managing keys

The first prediction for a key_id persists your secret key to ~/.implicant/keys/<key_id>/secret_key.bin (mode 0600) so later runs skip keygen. Inspect and clean up the local store:

implicant keys list            # list key_ids; flags which have a persisted SK
implicant keys rm <key_id>     # delete one stored key (secret + public)
implicant keys purge --yes     # delete all stored keys

Use (Python)

The same flow is available programmatically:

from implicant import ImplicantClient, list_known_models, sample_row
from implicant.transport import HttpxTransport

for m in list_known_models():          # discover: (slug, description) pairs
    print(m.slug, "—", m.name)

row = sample_row("diabetes")           # fresh mutable copy of the bundled example
row["time_in_hospital"] = 2.0          # hand-tweak values for testing

model = next(m for m in list_known_models() if m.slug == "diabetes")
client = ImplicantClient(
    HttpxTransport(base_url="https://api.implicant.example", api_key="imp_..."),
    key_cache_dir="~/.implicant/keys",
)
result = client.predict("diabetes", row, class_names=model.class_names)
print(result.prediction.label)

Demo mode

Demo mode skips FHE key generation by loading a pre-generated keypair shipped inside the package, and skips the public-key upload (the platform already holds the matching public bundle). It exists so a prediction can run immediately in a live demo, without first-use key generation and without uploading the multi-hundred-megabyte public key set. In this release it is required: predict refuses to run outside demo mode.

Activate with an environment variable (applies to the whole session):

export IMPLICANT_DEMO=1
implicant predict -m cancer -i row.json

Or per-command — combined with --sample, this is a zero-setup end-to-end run:

implicant predict -m cancer --sample --demo

All five registry models (credit, bankfraud, heartdisease, cancer, diabetes) are provisioned with bundled demo keys; a model ID without a bundled key raises an error in demo mode.

Security warning — demo mode is not private. The demo secret key is shipped inside the package and is therefore public: anyone with the wheel can decrypt anything encrypted in demo mode. Never use demo mode for real or sensitive data. Normal mode (the default) generates a secret key that never leaves your machine.

Web UI (demo)

A local web interface for live demonstrations — the four-step flow (choose a model, generate keys on your machine, watch your row get encrypted, see the blind result) with every visual driven by the real pipeline: a live execution-path strip, genuine per-phase timings, the exact encrypted payload and response sizes, a plain-words inventory of what the request contains, and an in-memory history of the session's inferences:

pip install "implicant[ui]"   # the ui extra ships from 0.7.0
export IMPLICANT_API_KEY="imp_..."
implicant ui        # starts a localhost server and opens your browser

All cryptography runs in the local Python process; the browser only renders. The UI is demo-only in this release and runs on the shared demonstration key (see the demo-mode warning above). On Windows, run the same UI via Docker:

docker build -t implicant-ui -f docker/Dockerfile .   # from the repo root
docker run --rm -p 8642:8642 \
  -e IMPLICANT_API_KEY=imp_... \
  -e IMPLICANT_API_URL=https://your-platform \
  implicant-ui
# then open the printed URL — including the #token — in your browser

Vision Rules — a third tab with a concept-bottleneck face demo (the 38 CelebA attributes → a short if-then rulebook → Female/Male, every fired rule spelled out in words; gallery faces, photo upload, webcam snapshot and live view). It runs the model in the clear on the serving machine and needs the optional [vision] extra (torch, torchvision, OpenCV, Pillow); without it the tab shows an install hint and nothing else changes:

pip install "implicant[ui,vision]"                     # macOS / Windows
# Linux: point pip at PyTorch's CPU index too (the CPU torch wheel is
# ~200 MB; PyPI's default Linux build pulls ~2 GB of CUDA):
PIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cpu pip install "implicant[ui,vision]"

The Docker image installs the extra already. The camera needs a secure page (localhost or HTTPS).

By default the page is protected by a per-launch URL token — the printed #fragment is the credential, so keep the full URL. For a deliberately public deployment behind a reverse proxy (e.g. a demo site), start with implicant ui --public-demo (or -e IMPLICANT_UI_PUBLIC_DEMO=1 in Docker): no token is required, visitors cannot change the server-side API key, and IMPLICANT_API_KEY must be set in the environment. Anyone who can reach the address can then drive the demo — never expose a private instance this way.

License

Apache-2.0.