Metadata-Version: 2.4
Name: cifer
Version: 1.0.48
Summary: Federated Learning and Fully Homomorphic Encryption
Home-page: https://github.com/cifer-ai/cifer
Author: Cifer.ai
Author-email: support@cifer.ai
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security :: Cryptography
Classifier: Framework :: Flask
Classifier: Framework :: FastAPI
Classifier: Environment :: Console
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26
Requires-Dist: requests<3,>=2.32
Requires-Dist: pandas<3.0,>=2.0
Requires-Dist: scikit-learn<2.0,>=1.3
Requires-Dist: tensorflow>=2.13
Requires-Dist: phe>=1.5
Requires-Dist: PyYAML>=6.0
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: websockets>=12
Requires-Dist: PyJWT>=2.8
Requires-Dist: pycryptodome>=3.20
Requires-Dist: python-dotenv>=1.0
Provides-Extra: server
Requires-Dist: grpcio>=1.60; extra == "server"
Requires-Dist: grpcio-reflection>=1.60; extra == "server"
Provides-Extra: vision
Requires-Dist: opencv-python; extra == "vision"
Requires-Dist: Pillow>=10.0; extra == "vision"
Provides-Extra: audio
Requires-Dist: librosa<1.0,>=0.10; extra == "audio"
Requires-Dist: torchaudio; extra == "audio"
Requires-Dist: pydub>=0.25; extra == "audio"
Provides-Extra: nlp
Requires-Dist: transformers>=4.40; extra == "nlp"
Requires-Dist: datasets; extra == "nlp"
Provides-Extra: graph
Requires-Dist: torch>=2.2; extra == "graph"
Requires-Dist: torch-geometric>=2.4; extra == "graph"
Requires-Dist: dgl; extra == "graph"
Provides-Extra: geo
Requires-Dist: geopandas; extra == "geo"
Provides-Extra: 3d
Requires-Dist: open3d; extra == "3d"
Provides-Extra: medical
Requires-Dist: pydicom; extra == "medical"
Provides-Extra: agent
Requires-Dist: fastapi<1.0,>=0.110; extra == "agent"
Requires-Dist: Flask<4.0,>=3.0; extra == "agent"
Requires-Dist: flask-cors<7.0,>=4.0; extra == "agent"
Requires-Dist: uvicorn>=0.29; extra == "agent"
Requires-Dist: redis>=5; extra == "agent"
Requires-Dist: keyring>=24; extra == "agent"
Requires-Dist: pydantic<3.0,>=2.0; extra == "agent"
Requires-Dist: cryptography<47,>=41; extra == "agent"
Requires-Dist: pyOpenSSL>=23; extra == "agent"
Provides-Extra: notebook
Requires-Dist: ipython>=8.12; extra == "notebook"
Requires-Dist: ipywidgets>=8.1; extra == "notebook"
Requires-Dist: nbclient>=0.9; extra == "notebook"
Requires-Dist: nbformat>=5.9; extra == "notebook"
Requires-Dist: notebook>=7.0; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: Sphinx<9,>=7.4; extra == "dev"
Requires-Dist: docutils<0.22,>=0.20; extra == "dev"
Requires-Dist: Cython<4,>=3.0; extra == "dev"
Provides-Extra: all
Requires-Dist: Cython<4,>=3.0; extra == "all"
Requires-Dist: Flask<4.0,>=3.0; extra == "all"
Requires-Dist: Pillow>=10.0; extra == "all"
Requires-Dist: Sphinx<9,>=7.4; extra == "all"
Requires-Dist: cryptography<47,>=41; extra == "all"
Requires-Dist: datasets; extra == "all"
Requires-Dist: dgl; extra == "all"
Requires-Dist: docutils<0.22,>=0.20; extra == "all"
Requires-Dist: fastapi<1.0,>=0.110; extra == "all"
Requires-Dist: flask-cors<7.0,>=4.0; extra == "all"
Requires-Dist: geopandas; extra == "all"
Requires-Dist: grpcio-reflection>=1.60; extra == "all"
Requires-Dist: grpcio>=1.60; extra == "all"
Requires-Dist: ipython>=8.12; extra == "all"
Requires-Dist: ipywidgets>=8.1; extra == "all"
Requires-Dist: keyring>=24; extra == "all"
Requires-Dist: librosa<1.0,>=0.10; extra == "all"
Requires-Dist: nbclient>=0.9; extra == "all"
Requires-Dist: nbformat>=5.9; extra == "all"
Requires-Dist: notebook>=7.0; extra == "all"
Requires-Dist: open3d; extra == "all"
Requires-Dist: opencv-python; extra == "all"
Requires-Dist: pyOpenSSL>=23; extra == "all"
Requires-Dist: pydantic<3.0,>=2.0; extra == "all"
Requires-Dist: pydicom; extra == "all"
Requires-Dist: pydub>=0.25; extra == "all"
Requires-Dist: pytest>=8.0; extra == "all"
Requires-Dist: redis>=5; extra == "all"
Requires-Dist: torch-geometric>=2.4; extra == "all"
Requires-Dist: torch>=2.2; extra == "all"
Requires-Dist: torchaudio; extra == "all"
Requires-Dist: transformers>=4.40; extra == "all"
Requires-Dist: uvicorn>=0.29; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<p align="left">
  <a href="https://cifer.ai/">
    <img src="https://cifer.ai/assets/themes/cifer/images/logo/ciferlogo.png" width="240" alt="Cifer Website" />
  </a>
</p>

Cifer is a **Federated Learning framework with integrated Fully Homomorphic Encryption (FHE)** for secure, decentralized model training and encrypted aggregation.

It improves model robustness, reduces bias, and handles distribution shift across non-IID data.

Supports both centralized and decentralized topologies by default, with optional Cifer Blockchain integration for auditability and provenance.

[![GitHub license](https://img.shields.io/github/license/CiferAI/ciferai)](https://github.com/CiferAI/ciferai/blob/main/LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/CiferAI/ciferai/blob/main/CONTRIBUTING.md)
[![Downloads](https://static.pepy.tech/badge/cifer)](https://pepy.tech/project/cifer)

[🌎 Website](https://cifer.ai) &nbsp;&nbsp;| &nbsp;
[📔 Docs](https://cifer.ai/documentation) &nbsp;&nbsp;| &nbsp;
[🙌 Join Slack](https://join.slack.com/t/cifertalk/shared_invite/zt-2y09cb0yu-zHYyNkiYWq6AfssvU2rLrA)

---
<br>

# Cifer Python Package (PyPI)

The cifer Python package provides a secure, programmatic interface for executing **Privacy-Preserving Machine Learning (PPML)** workflows. It enables local and distributed model training using **Federated Learning (FL)** and **Fully Homomorphic Encryption (FHE)**—without ever exposing raw data.

This package is ideal for Python developers, researchers, and data scientists who need fine-grained control over federated workflows within trusted or adversarial environments.

For alternative development workflows:

* Use the[ Cifer Python Package](https://pypi.org/project/cifer) for direct integration into custom Python-based ML pipelines
* Use[ Cifer Workspace](https://workspace.cifer.ai) for browser-based, no-code orchestration and collaborative workspace

---
<br>

# What is Cifer Federated Learning?

**Cifer Federated Learning (FedLearn)** is a secure training framework that enables collaborative machine learning across distributed data sources—without ever sharing raw data. Each participant (or node) performs local training, and only encrypted model updates are exchanged across the network.

Rather than centralizing data into a vulnerable repository, Cifer coordinates encrypted computations between participants, preserving **data sovereignty, compliance,** and **confidentiality** across jurisdictions and organizations.

## Key Extensions Beyond Standard FL

* **Fully Homomorphic Encryption (FHE)** \
  Cifer integrates FHE at the protocol level, allowing model updates and gradients to be computed on encrypted tensors. This ensures data remains encrypted throughout the lifecycle—including training, aggregation, and communication.\
  Unlike differential privacy (DP), which introduces noise and cannot fully prevent reconstruction attacks, FHE offers cryptographic guarantees against adversarial inference—even in hostile environments.

* **Dual Topology Support: Centralized and Decentralized** \
  Cifer supports both:
  * **Client–Server (cFL):** A central coordinator aggregates updates from authenticated participants—ideal for trusted, enterprise-level deployments.
  * **Peer-to-Peer (dFL):** Participants can operate without a central aggregator, enabling direct encrypted update exchanges across nodes for higher resilience.

* **Secure Communication Channels**\
  All communication is conducted over **gRPC**, leveraging **HTTP/2** and Protocol Buffers for efficient, multiplexed, and encrypted transport. This ensures fast synchronization while minimizing attack surfaces.

* **Blockchain Integration** (Optional)\
  For use cases requiring immutable audit trails, decentralized identity, or consensus-based coordination, Cifer supports integration with its proprietary **Cifer Blockchain Network**, providing an additional layer of provenance and tamper resistance.

## Federated Learning and the Adversarial Threat Model

Standard federated learning protocols are susceptible to:

* Gradient leakage and model inversion attacks
* Malicious participant injection
* Data reconstruction through side-channel inference

The industry trend has been to use differential privacy (DP) to mitigate these threats. However:

* DP requires complex tuning of privacy budgets (ε, δ)
* It introduces statistical noise, reducing model accuracy
* It provides probabilistic—not cryptographic—guarantees, and can still leak information under repeated queries or cumulative exposure


Cifer’s FHE-based design **eliminates these risks** by ensuring that all shared model artifacts remain mathematically unreadable, even under active attack or node compromise.

## Performance Capacity

Cifer FedLearn is built for real-world scale:

* Supports **client-server and P2P** topologies
* Tested for **model sizes and parameter transfers up to 30GB**
* Optimized for **GPU acceleration, NUMA-aware compute,** and **multi-node orchestration**

## Core Modules

* **FedLearn**\
  Orchestrates decentralized training across multiple nodes while maintaining data locality. Supports both:
  * **Centralized FL (cFL)** for governed, trusted environments
  * **Decentralized FL (dFL)** with peer coordination across encrypted channels
* **HomoCryption (FHE)**\
  Allows computation on encrypted data throughout the training lifecycle, preserving privacy even during intermediate operations.

## Key Capabilities

* **Hybrid Federation Support**\
  Choose between cFL or dFL architectures depending on governance, trust, and fault tolerance requirements.
* **Secure Communication Protocol**\
  Powered by gRPC with HTTP/2 and Protocol Buffers:
  * Low-latency streaming
  * Compact serialized messages
  * Built-in encryption and authentication
* **End-to-End Encrypted Computation**\
  FHE is embedded directly into the training workflow. No intermediate decryption. Data privacy is mathematically guaranteed.

---
<br>

# Before Getting Started

To ensure a smooth experience using Cifer for Federated Learning (FL) and Fully Homomorphic Encryption (FHE), please verify your system meets the following baseline requirements:

## System Requirements

* **Operating System**
  * Linux (Ubuntu 18.04 or later)
  * macOS (10.14 or later)
  * Windows 10 or later
* **Python**
  * Version: 3.9 (only version officially supported)
* **Memory**
  * Minimum: 8 GB RAM
  * Recommended: 16 GB+ for large-scale training or encryption tasks
* **Storage**
  * At least 30 GB of available disk space
* **Network**
  * Stable internet connection (required for remote collaboration or coordination modes)

## GPU Acceleration (Optional)

Cifer supports GPU acceleration for both FL and FHE components using:

* **NVIDIA CUDA** (for TensorFlow, PyTorch pipelines)
* **Google TPU** (via JAX and compatible backends)

While GPU is not mandatory, it is highly recommended for encrypted training at scale or production-grade deployments.

---
<br>

# Getting Started with Cifer’s Federated Learning

Cifer provides a modular Federated Learning (FL) framework that enables privacy-preserving model training across distributed environments. To get started, install the package via pip, import the required modules, and choose your preferred communication method for orchestration.

## What's Included in pip install cifer

Installing Cifer via pip provides the following components and features:

### **Core Modules**

* **FedLearn:** Federated learning engine for decentralized model training.
* **HomoCryption:** Fully Homomorphic Encryption (FHE) for computation on encrypted data.

**Integrations**

* **Built-in compatibility with** TensorFlo&#x77;**,** PyTorch, scikit-learn, NumPy, CUDA, JAX, Hugging Face Transformers.

**Utilities**

* Data preprocessing tools
* Privacy-preserving metrics
* Secure aggregation algorithms

**Cryptographic Libraries**

* Integration with advanced homomorphic encryption backends

**Communication Layer**

* gRPC-based secure communication protocols for FL orchestration

**Command-Line Interface (CLI)**

* CLI client for managing experiments and configurations

**Example Notebooks**

* Jupyter notebooks demonstrating end-to-end workflows

## **Optional Dependencies**

Install extras using:

```bash
pip install "cifer[server]"
```

Options:

* `server`: gRPC / WebSocket server dependencies
* `vision`: Vision-related helpers
* `audio`: Audio-related helpers
* `nlp`: Transformer-related helpers
* `graph`: Graph dataset / PyG helpers
* `geo`: Geospatial helpers
* `3d`: 3D helpers
* `medical`: Medical imaging helpers
* `agent`: API / agent runtime dependencies
* `notebook`: Jupyter and notebook tooling
* `dev`: test and documentation tooling
* `all`: Installs all optional dependencies

---
<br>

# 1. Install Cifer

```bash
pip install cifer
```

To include all optional features:

```bash
pip install "cifer[all]"
```

---
<br>

# 2. Quick Start

For the current package, the most reliable starting point is the CLI demo flow.

## Create a Project

```bash
cifer init my-cifer-project
```

This creates a local project skeleton with:

* `dataset/`
* `models/`
* `config.yaml`

## Create a Toy Dataset

```bash
cifer dataset toy --output demo_artifacts/toy_dataset.npz
```

## Run a One-Command Local Demo

```bash
cifer demo train --output-dir demo_artifacts --epochs 3
```

This command:

* creates a minimal `.npz` dataset
* creates a default `.keras` model
* trains locally and prints the final accuracy

---
<br>

# 3. Python API

The current Python API centers on `CiferClient`, `CiferServer`, and `securetrain`.

## Import Modules

```python
from cifer import CiferClient, CiferServer, CiferConfig
from cifer.securetrain import (
    generate_named_keys,
    encrypt_dataset,
    train_model,
    decrypt_dataset,
    decrypt_model,
)
```

## Dataset Format

For standard local training, `CiferClient` expects a `.npz` dataset containing:

* `train_images`
* `train_labels`

For graph workloads, use a `.pt` dataset instead.

## Local Client Example

```python
from cifer import CiferClient

client = CiferClient(
    encoded_project_id="YOUR_PROJECT_ID",
    encoded_company_id="YOUR_COMPANY_ID",
    encoded_client_id="YOUR_CLIENT_ID",
    base_api="https://workspace.cifer.ai/FederatedApi",
    dataset_path="dataset/toy_dataset.npz",
    model_path="models/toy_model.keras",
    use_encryption=False,
    epochs=3,
)

model, accuracy = client.train_model()
print("accuracy:", accuracy)
```

If `model_path` does not exist yet, Cifer will create a default Keras model automatically for standard `.npz` datasets.

## Multi-round Federated Training

Start a three-client WebSocket server:

```bash
export CIFER_JWT_SECRET="a-secret-with-at-least-32-bytes"
python examples/run_federated_server.py
```

In another terminal, start three clients with separate local datasets:

```bash
export CIFER_JWT_SECRET="a-secret-with-at-least-32-bytes"
python examples/run_federated_clients.py \
  --dataset client_a.npz client_b.npz client_c.npz \
  --rounds 3 \
  --epochs 1
```

For each round, authenticated clients receive the latest global Keras weights,
train locally, submit their update with the local sample count, wait for
weighted FedAvg, and save the returned global model. A client can use the same
flow directly:

```python
history = client.run_federated_rounds(
    server_uri="ws://127.0.0.1:8765",
    token=jwt_token,
    rounds=3,
)
```

Each authenticated client can submit only one update per named round.

---
<br>

# 4. CLI Commands

Common commands:

```bash
cifer version
cifer init my-project
cifer dataset toy --output demo_artifacts/toy_dataset.npz
cifer demo train --output-dir demo_artifacts --epochs 3
cifer client --dataset demo_artifacts/toy_dataset.npz --project-id ... --company-id ... --client-id ... --model-path demo_artifacts/toy_model.keras
cifer securetrain encrypt-dataset --dataset data.csv --output encrypted.json --key demo
```

Available command groups:

* `securetrain`
* `dataset`
* `demo`

Top-level commands include:

* `version`
* `init`
* `server`
* `client`
* `status`
* `register-kernel`
* `agent-ace`
* `download-notebook`

## Notes on Federated APIs

The package currently exposes:

* `CiferClient` for local training and upload flow
* `CiferServer` for aggregation/upload flow
* `run_federated_server(...)` for the lower-level runner

Older examples that reference `fl.Server()` or `fl.strategy.FedAvg(...)` do not match the current implementation and should not be used as the primary integration path.

---
<br>

# Getting Started with Cifer’s Homomorphic Encryption (FHE)

Cifer includes a built-in homocryption module for Fully Homomorphic Encryption (FHE), allowing computation on encrypted tensors without exposing raw data. You can encrypt, perform arithmetic, relinearize, and decrypt—all while preserving confidentiality.

## 1. Import HomoCryption Module

```python
from cifer.securetrain import (
   generate_named_keys,
   encrypt_dataset,
   train_model,
   decrypt_model,
)
```

## 2. Generate Keys

```python
from cifer.securetrain import generate_named_keys

generate_named_keys("demo")
```

## 3. Encrypt Data

```python
from cifer.securetrain import encrypt_dataset

encrypt_dataset("data.csv", "encrypted_dataset.json", "demo")
```

## 4. Perform Encrypted Computation

Train on encrypted data:

```python
from cifer.securetrain import train_model

train_model(
    encrypted_path="encrypted_dataset.json",
    output_model_path="encrypted_model.pkl",
    key_name="demo",
    feature_cols=["feature_a", "feature_b"],
    label_col="label",
)
```

Apply relinearization to manage ciphertext noise:

```bash
# Encrypt two vectors
vec1 = ts.ckks_vector(context, [1.0, 2.0, 3.0])
vec2 = ts.ckks_vector(context, [4.0, 5.0, 6.0])

# Multiply and relinearize
encrypted_result = vec1 * vec2
encrypted_result.relinearize()  # 👈 This is the relinearize step
decrypted = encrypted_result.decrypt()
```

## 5. Decrypt Result

```python
from cifer.securetrain import decrypt_dataset, decrypt_model

decrypt_dataset("encrypted_dataset.json", "decrypted_dataset.csv", "demo")
decrypt_model("encrypted_model.pkl", "decrypted_model.pkl", "demo")
```

| **Operation**  | **Method**         | **Compatible with Aggregation** |
| -------------- | ------------------ | ------------------------------- |
| Addition       | `hc.add()`         | ✅ Yes                           |
| Multiplication | `hc.mul()`         | ⚠️ Partially (check noise)      |
| Relinearize    | `hc.relinearize()` | ✅ Required after `mul()`        |
| Decryption     | `hc.decrypt()`     | 🔐 Private key required         |

---
<br>

# FHE in Aggregation Context

When using FHE-enabled federated learning:

* Each client encrypts model weights before sending
* The server performs aggregation (e.g., summing encrypted tensors)
* Final decryption happens at a trusted node after aggregation
* Only compatible operations (addition, averaging) are supported

> ⚠️ If FHE is enabled, make sure your aggregation strategy supports encrypted arithmetic.

---
<br>

# Learn More

For detailed examples, deployment patterns, and advanced configurations:

* Full documentation:[ https://www.cifer.ai/docs](https://www.cifer.ai/docs)
* GitHub repository:[ https://github.com/ciferai/cifer](https://github.com/ciferai/cifer)
* Developer support: support@cifer.ai


Description not available.
