Metadata-Version: 2.3
Name: lattica-fhe-core
Version: 0.1.6
Summary: Lattica FHE Core Python Bindings
Author: LatticaAI
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Description-Content-Type: text/markdown

# Lattica FHE Core

This repository contains the source code for the **Lattica Client FHE SDK**, which powers encrypted inference for AI workloads using Fully Homomorphic Encryption (FHE). The SDK provides a portable FHE implementation that compiles into a shared library used both by the Lattica Python and JS clients.

---

## 🛠️ Build Instructions

### Requirements

#### Linux x86_64 or macOS ARM-64

- C++17-compatible compiler (e.g. `g++ ≥ 9`)
- CMake ≥ 3.14
- Python ≥ 3.8
- `pybind11`
- `torch == 2.5.1`
- `setuptools`, `wheel` (for Python packaging)

##### macOS only:

- autoconf, automake

### Build Steps

```bash
git clone https://github.com/Lattica-ai/lattica_fhe_core.git
cd lattica_fhe_core

# Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate

# Install required Python packages
pip install pybind11 torch==2.5.1 setuptools wheel

# Build the project
cmake . -B build -DPYTHON_ENABLED=ON
cmake --build build --parallel 32
```

This will generate a Python extension shared library named like:

```
# On Linux:
cpp_sdk.cpython-312-x86_64-linux-gnu.so

# On macOS:
cpp_sdk.cpython-312-darwin.so
```

---

## ▶️ Using This Build in the Lattica Client

To replace the binary distributed by `lattica-query`:

1. Install the query client as described here:  
   👉 https://platformdocs.lattica.ai/how-to-guides/client-installation/how-to-install-query-client

2. Locate the installed `.so` file by running:

```bash
pip show -f lattica-fhe-core
```

3. Replace the installed `cpp_sdk.*.so` file with the one you built.

---

## 📁 Project Structure

A detailed breakdown of the major components in this repository:

---

### `src/encryption_schemes/`

Implements the supported encryption schemes used by the Lattica client.

- Includes `ckks`, `rbgv`, and two GSW-like variants (`*_g`, `*_g_crt`) based on gadget matrix decompositions.
- Each scheme provides:
  - Encoding and decoding of plaintext data
  - Encryption and decryption procedures
  - Key generation, including auxiliary key-switching keys
- All cryptographic randomness is generated via **Libsodium**

---

### `src/context_utils/`

Provides utilities for interpreting and validating encryption context parameters.

- Parameters are received from the backend per model — they are not generated locally.
- Includes logic for:
  - Representing data in **double-CRT form**
  - Managing modulus chains and per-prime decompositions
  - Ensuring structural compatibility of runtime contexts

---

### `src/homomorphic_operations/`

Implements **apply-clear** versions of homomorphic operations.

- These simulate encrypted computation by applying the logic directly to plaintext inputs.
- Used only for client-side validation and debugging — no encrypted computation is performed here.
- Actual homomorphic execution is handled remotely by the Lattica backend.

---

### `src/binding/python/`

Defines the Python interface via `pybind11`.

- These four functions are exposed:
  1. `py_generate_key(...)`
  2. `py_enc(...)`
  3. `py_dec(...)`
  4. `py_apply_client_block(...)`

---

### `src/encryption_scheme_utils/`

Implements abstractions for representing and manipulating the structure of plaintext data.

- Defines the `pt_shape` object, which describes logical dimensions, padding, and layout

---

### `src/tensor_engine/`

Implements the core arithmetic and layout handling logic for encrypted and plaintext data.

- All data — including ciphertexts, plaintexts, and context elements — is represented as **tensors**
- Built on **PyTorch tensor operations**, with select extensions for FHE-specific requirements
- Includes custom kernels for modular arithmetic routines: addition, multiplication, NTT, inverse NTT

---

### `src/serialization/`

Handles serialization and deserialization of all major objects.

- Implemented using **Protocol Buffers (protobuf)**
- Supports efficient encoding of ciphertexts, plaintexts, keys, and context objects

---

### `src/slot_permutation/`

Implements **coefficient permutations**, supports both:

- Permutations in the **coefficient basis**
- Permutations in the **CRT basis**

---

### `src/` (top-level)

- `num.cpp`: Implements **multi-precision integer arithmetic**
- `toolkit_python.cpp`: Entry point for the Python integration layer

---

## 🔐 License

See [LICENSE.txt](./LICENSE.txt) for license details.

For support, please contact the Lattica team or consult internal documentation.

