Metadata-Version: 2.4
Name: vaultstream-sdk
Version: 1.0.0
Summary: Python client SDK for VaultStream — Homomorphic Encryption-as-a-Service for cloud computing
Author-email: Leeroy Muguti <leeroymuguti@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/p4yl0adgeek/vaultstream
Project-URL: Documentation, https://github.com/p4yl0adgeek/vaultstream/blob/main/vaultstream-sdk/README.md
Project-URL: Repository, https://github.com/p4yl0adgeek/vaultstream
Project-URL: Issues, https://github.com/p4yl0adgeek/vaultstream/issues
Keywords: homomorphic-encryption,cryptography,privacy,cloud-computing,tenseal,ckks,bfv,sdk,heaas
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tenseal>=0.3.16
Requires-Dist: httpx>=0.28.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# VaultStream Python SDK

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

[![PyPI](https://img.shields.io/pypi/v/vaultstream-sdk.svg)](https://pypi.org/project/vaultstream-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/vaultstream-sdk.svg)](https://pypi.org/project/vaultstream-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

---

## Installation

```bash
pip install vaultstream-sdk
```

> **Note:** This SDK depends on [TenSEAL](https://github.com/OpenMined/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](https://github.com/OpenMined/TenSEAL#installation) if you hit a build error.

## Quick Start

```python
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](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.
