Metadata-Version: 2.4
Name: supersayan
Version: 0.1.2
Summary: A high-performance Python library for fully homomorphic encryption (FHE) in deep learning, seamlessly integrated with PyTorch.
Author-email: bonsainoodle <3sprix.exe@gmail.com>, franklintra <franklin.tranie@gmail.com>
Project-URL: GitHub, https://github.com/yourusername/supersayan
Keywords: homomorphic-encryption,FHE,deep-learning,pytorch,privacy-preserving,cryptography,neural-networks,secure-computation,machine-learning,julia
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: torch>=2.0.0
Requires-Dist: julia>=0.6.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: requests>=2.25.0
Requires-Dist: torchvision>=0.15.0
Requires-Dist: websocket-client>=1.8.0
Requires-Dist: torchsummary>=1.5.1
Requires-Dist: python-socketio>=5.13.0
Requires-Dist: simple-websocket>=1.1.0
Requires-Dist: juliacall>=0.9.25
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: scalene>=1.5.51; extra == "dev"
Provides-Extra: publish
Requires-Dist: twine>=4.0.0; extra == "publish"
Requires-Dist: build>=0.10.0; extra == "publish"
Dynamic: license-file

# Supersayan

A high‑performance Python library that integrates Fully Homomorphic Encryption (FHE) into PyTorch workflows. Supersayan provides:

- A client/server path to offload selected layers to a remote FHE server (hybrid mode).
- Zero‑copy tensor bridges across PyTorch, NumPy, CuPy, and Julia.

The Julia backend is managed via `juliacall` and initialized automatically on first import, or explicitly with a helper CLI.

## Installation

From PyPI:

```bash
pip install supersayan
# or with uv
uv add supersayan
```

Default behavior:
- After install, importing `supersayan` triggers a one‑time Julia backend setup automatically. No extra step is needed for typical users.

Optional (CI/Docker or troubleshooting):

```bash
# Manually initialize the Julia backend if you want explicit control
supersayan-setup
```

Advanced control (not recommended for regular users):
- To prevent network access during import in CI images, set `SUPERSAYAN_SKIP_JULIA_SETUP=1` and run `supersayan-setup` in a controlled build step.

Notes:
- GPU support uses CuPy when available; code runs on CPU otherwise.

## Hybrid Remote Inference

Run the TCP server:

```bash
python scripts/run_server.py --host 127.0.0.1 --port 8000 --models-dir /tmp/supersayan/models
```

Use the client to execute only selected layers remotely in FHE while keeping other ops local:

```python
import torch
import torch.nn as nn
from supersayan.core.types import SupersayanTensor
from supersayan.remote import SupersayanClient

class SmallCNN(nn.Module):
    def __init__(self):
        super().__init__()
        self.conv = nn.Conv2d(1, 4, 3, padding=1)
        self.fc = nn.Linear(4*28*28, 10)
    def forward(self, x):
        x = torch.relu(self.conv(x))
        return self.fc(x.view(x.size(0), -1))

cnn = SmallCNN().eval()
client = SupersayanClient(
    server_url="127.0.0.1:8000",
    torch_model=cnn,
    fhe_modules=[nn.Conv2d, nn.Linear],  # offload these layers
)

x = SupersayanTensor(torch.randn(1, 1, 28, 28))
y = client(x)
```

For a runnable example of the TCP server, see `scripts/run_server.py`.

Supported offloaded layers: `nn.Linear`, `nn.Conv2d`.

## Tensors and Interop

- `SupersayanTensor(data, device=...)` accepts `torch.Tensor`, `numpy.ndarray`, or `cupy.ndarray` and preserves dtype float32.
- Helpers: `SupersayanTensor.zeros(...)`, `ones(...)`, `randn(...)`.
- Interop: `.to_numpy()`, `.to_dlpack()`, and zero‑copy conversion to Julia via `.to_julia()`.

## Project Layout

- `src/supersayan/` core, layers, remote client/server, Julia backend
- `scripts/` runnable examples (`run_server.py`)

## Troubleshooting

- If Julia setup fails on first import, run `supersayan-setup` manually.
- In CI or headless environments, set `SUPERSAYAN_SKIP_JULIA_SETUP=1` during import and run `supersayan-setup` explicitly in a build step.
