vaultstream-sdk 1.0.0

Python client SDK for VaultStream — Homomorphic Encryption-as-a-Service for cloud computing

VaultStream Python SDK

Official Python client library for VaultStream — a Homomorphic Encryption-as-a-Service (HEaaS) platform for cloud computing.

Compute on encrypted data in the cloud — without ever exposing plaintext or private keys to the cloud provider.

---

Installation

pip install vaultstream-sdk

Note: This SDK depends on TenSEAL, which provides the underlying homomorphic encryption primitives. TenSEAL ships pre-built wheels for most platforms but may require a C++ build toolchain on some systems. See the TenSEAL installation guide if you hit a build error.

Quick Start

from vaultstream import VaultStreamClient

# Connect to the VaultStream API
client = VaultStreamClient(
    api_url="https://your-vaultstream-instance.cloudapp.azure.com",
    api_key="vs_live_xxxxxxxxxxxx",
    scheme="ckks",          # or "bfv" for exact integer arithmetic
)

# Verify connectivity
print(client.ping())

# Generate encryption keys client-side. The private key never leaves
# this process. The public context is uploaded to the server once and
# cached for subsequent operations.
client.generate_keys()

# Compute encrypted sum — data is encrypted locally, sent to the
# server as ciphertext, summed homomorphically, and returned encrypted.
# The plaintext result is only visible here, after local decryption.
result = client.encrypted_sum([100.0, 250.5, 175.25, 400.0])
print(f"Sum: {result}")     # 925.75

# Other operations available
client.encrypted_average([100, 200, 300])
client.encrypted_min_max([45, 89, 12, 67, 23])
client.encrypted_variance([10, 20, 30, 40, 50])
client.encrypted_correlation(x=[1, 2, 3], y=[2, 4, 6])
# ...

Privacy Guarantees

• Private keys never leave your application. Keys are generated and held inside the VaultStreamClient instance only.
• The VaultStream service never sees plaintext. All values are encrypted client-side before any network transmission.
• Results are decrypted locally using your private key, inside this client.
• Cryptographic, not procedural, privacy. Privacy is enforced by the math (TenSEAL's BFV and CKKS implementations), not by a service-level promise.

Supported Operations

The SDK provides client-side wrappers for all VaultStream API operations:

Operation	Method	Scheme
Sum	encrypted_sum(values)	CKKS, BFV
Average	encrypted_average(values)	CKKS, BFV
Min/Max	encrypted_min_max(values)	CKKS
Variance & Std Dev	encrypted_variance(values)	CKKS
Threshold count	encrypted_threshold_count(values, threshold)	CKKS
Weighted average	encrypted_weighted_average(values, weights)	CKKS
Pearson correlation	encrypted_correlation(x, y)	CKKS
Percentile ranking	encrypted_percentiles(values)	CKKS
Histogram	encrypted_histogram(values, bins)	CKKS
Count	encrypted_count(values)	BFV

Schemes

• CKKS — approximate floating-point arithmetic. Use for financial analytics, statistical aggregates, ML inference.
• BFV — exact integer arithmetic. Use for vote counting, integer aggregations, equality checks.

Architecture

Your Application                    VaultStream API
─────────────────                   ───────────────
plaintext values                    
      │
      │ SDK encrypts locally
      ▼
  ciphertext  ────── HTTPS ──────►  ciphertext
                                          │
                                          │ HE operation
                                          ▼
                                    encrypted result
  decrypted ◄────── HTTPS ─────────  encrypted result
      │
      │ SDK decrypts locally
      ▼
plaintext result

The server only ever holds ciphertext and the public context. Your private key stays in your process memory.

Authentication

You need an API key from a VaultStream instance to use this SDK. API keys look like vs_live_xxxxxxxxxxxx and are scoped to one tenant organisation.

Project Status

VaultStream is a capstone research project at the University of Zimbabwe (Department of Applied Informatics) exploring practical deployment of Homomorphic Encryption in cloud environments. The SDK is published on PyPI to demonstrate that any organisation can integrate VaultStream into existing Python systems with one pip install.

License

MIT — see LICENSE.

Citation

If you use VaultStream in academic work, please cite:

Muguti, L. (2026). Homomorphic Encryption in Cloud Computing. Honours Capstone, University of Zimbabwe, Department of Applied Informatics.