HE application for the K3s lab

Local SDK

The repository also builds the he_looming_sdk Python distribution. Its OpenFHE adapter reuses openfhe_cpu/runtime.py, which is the same function layer used by the CPU HTTP evaluator. Application developers therefore get a different wrapper, not a second implementation of the HE calculations.

from he_sdk import HESession

with HESession.create(backend="openfhe") as he:
    values = he.encrypt([1.0, 2.0, 3.0, 4.0])
    encrypted_result = he.variance(values)
    result = he.decrypt(encrypted_result)

Version 0.4 also supports an SDK-only, secretless filesystem handoff:

# Owner process
owner = HESession.create(backend="openfhe")
encrypted = owner.encrypt([10.0, 20.0, 30.0])
owner.save(encrypted, "./he-workspace", name="input")

# Separate compute process
with HESession.open_workspace("./he-workspace") as compute:
    encrypted = compute.load("./he-workspace", name="input")
    compute.save(compute.sum(encrypted), "./he-workspace", name="sum")

The two-kernel tutorial is under examples/notebooks/; see docs/he-sdk-workspace.md for the artifact and trust-boundary contract.

GitLab CI builds the wheel and runs native OpenFHE integration tests. Local development only needs the dependency-free contract tests. The FIDES local SDK backend is an optional he-sdk-fides native plugin built by the CUDA CI path; it is published only after its T4 equivalence gate passes. See docs/he-sdk.md, docs/he-sdk-fides.md, and compatibility/he-sdk-v1.toml. The current-vs-target layer boundaries and deliberately smaller remote roadmap are in docs/he-sdk-architecture.md.

Version tags matching pyproject.toml publish the wheel to public PyPI and to this project's private GitLab PyPI registry. See docs/he-sdk-pypi.md for public publishing and docs/he-sdk-gitlab-registry.md for the private fallback.

The successful CPU image contains the verified wheel at /opt/he-sdk-wheel/he_looming_sdk-*.whl. The GitOps repository provides scripts/sdk/run-smoke.sh cpu-<short-sha> to install and execute it in a K3s Job without modifying the server host.

For the first persistent storage trial, compose.postgres.yaml runs a separate PostgreSQL container with a durable named volume. Its initial schema stores SDK run metadata and encrypted/public artifacts only; it intentionally rejects a secret_key artifact type. See postgres/README.md.

This repository now builds one secretless CPU OpenFHE evaluator. The first scope is intentionally small:

• primitives: add, subtract, multiply;
• unary: square;
• reductions: sum, mean, variance (population variance).

The API accepts serialized CKKS context, evaluation keys when required, and ciphertexts. It never accepts plaintext or a secret key and returns only a result ciphertext.

CPU and GPU stay separate

k3s-demo-app/Dockerfile              k3s-demo-app/gpu/Dockerfile
standard openfhe-python              FIDESlib + its patched OpenFHE
CPU image/process                    CUDA GPU image/process

Do not install or link standard OpenFHE and FIDESlib's patched OpenFHE in the same image or process. Both images are built from this repository, but remain independent processes. The GPU worker receives serialized artifacts through its HTTP adapter and performs the HE operations in native FIDESlib C++.

The small operation list is in common/operations.py. The seven explicit CPU defaults and direct functions live in openfhe_cpu/runtime.py, and the serialized evaluator adapter lives in backends/openfhe_python.py. The matching FIDESlib methods live in gpu/worker/src/fides_backend.cpp. The HTTP layer contains no HE-library calls. Parameter profiles and workflow contracts are intentionally left for later.

Evaluator API

GET  /healthz
GET  /readyz
GET  /v1/capabilities
POST /v1/evaluate
POST /v1/demo/evaluate
POST /v1/demo/bgv/evaluate

/v1/demo/bgv/evaluate is a trusted CPU-only integer multiplication check. It creates a BGV context, encrypts packed integer vectors, performs EvalMult or EvalSum, decrypts, and reports timings. The production-style secretless /v1/evaluate contract remains CKKS; FIDESlib GPU remains CKKS-only.

Primitive request:

{
  "operation": "add",
  "context": "<base64>",
  "ciphertext_a": "<base64>",
  "ciphertext_b": "<base64>"
}

multiply and square require evaluation_keys containing serialized EvalMult keys. sum and mean use one ciphertext plus rotation keys:

{
  "operation": "sum",
  "context": "<base64>",
  "ciphertext_a": "<base64>",
  "evaluation_keys": "<base64 serialized automorphism/SUM keys>",
  "valid_count": 8192,
  "request_id": "optional-run-id"
}

variance composes E[x²] - E[x]² and therefore needs both key types. It uses explicit multiplication_keys and rotation_keys fields instead of the legacy single evaluation_keys field.

For data larger than one CKKS batch, the trusted client encrypts chunks, calls sum for each chunk, then combines the encrypted partial scalars with add. See docs/he-main-api-function-matrix.md for the complete function/key table and the next implementation order.

GitLab pipeline

Contract tests require no HE installation. On the default branch, GitLab CI builds and pushes:

docker.io/dockerboi99/he_k8s:cpu-<short-commit-sha>
docker.io/dockerboi99/he_k8s:cpu-latest
docker.io/dockerboi99/he_k8s:gpu-<short-commit-sha>
docker.io/dockerboi99/he_k8s:gpu-latest

Deploy the commit tag on cached or mirrored registries. latest is only a convenience alias; it is not a reliable deployment identity because a mirror may continue serving an older digest for the moving tag.

The CPU image uses standard openfhe-python and starts python -m api.app. It also contains NumPy and Pandas so the same CPU image can be used as the non-GPU client for an in-cluster comparison Job; the evaluator service does not import them. The GPU image is built separately from gpu/Dockerfile and contains FIDESlib plus its patched OpenFHE. Neither HE runtime is copied into the other image.

Both image pushes require masked project CI/CD variables DOCKERHUB_USERNAME and DOCKERHUB_TOKEN. The Docker Hub token needs read/write permission. CPU builds automatically; the GPU build remains manual.

Run the dependency-free tests with:

python3 -m unittest discover -s tests -v

For a direct CPU check before Docker or K3s, install requirements.txt and run:

python -m client.direct_openfhe_cpu_test

See docs/direct-openfhe-library.md for the short direct-library setup and the seven checked operations.

The parameter trade-offs and later optimization checkpoint are recorded in docs/he-parameter-optimization-note.md.

The older gateway/, he_client/, and related examples remain as historical trusted plaintext/session trial code. They are tested but are not copied into the evaluator image.

See docs/encrypted-evaluator-implementation.md for the short implementation and server-test plan.