# crypto-starlab/thor architecture

> Architecture diagram of the GitHub repository crypto-starlab/thor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crypto-starlab/thor
- Repository: https://github.com/crypto-starlab/thor

## Overview

THOR is a library for evaluating BERT-style models over CKKS homomorphic encryption, using Liberate as its cryptographic backend. The principal workflow is to encode model inputs and weights, run encrypted transformer operations and approximated nonlinear functions, then rely on CKKS encryption and evaluation primitives (including bootstrapping) to preserve computation on ciphertexts. The README identifies running the HE model as the product task but its notebook and downloaded data are absent. Relationships below follow shown imports, excerpts, and README statements; unsampled internals are not inferred beyond those references.

Main entry points: [`src/thor/bert.py`](https://github.com/crypto-starlab/thor/blob/main/src/thor/bert.py) (BERT layers), [`liberate/src/liberate/fhe/ckks_engine.py`](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/ckks_engine.py) (CKKS engine), [`liberate/src/liberate/fhe/context/ckks_context.py`](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/context/ckks_context.py) (CKKS parameters), [`src/thor/ckks.py`](https://github.com/crypto-starlab/thor/blob/main/src/thor/ckks.py) (THOR CKKS adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model preparation"]
  node_model_encoder["Model encoder<br/>[model_encoder.py]"]
  node_model_data["Model data<br/>[data.py]"]
end

subgraph group_thor["Encrypted inference"]
  node_bert["BERT layers<br/>[bert.py]"]
  node_linear["Linear evaluator<br/>[linear.py]"]
  node_polynomial["Polynomial evaluator<br/>[polynomial.py]"]
  node_softmax["Encrypted softmax<br/>[softmax.py]"]
  node_gelu["Encrypted GELU<br/>[gelu.py]"]
  node_layernorm["Encrypted layer norm<br/>[layernorm.py]"]
  node_tanh["Encrypted tanh<br/>[tanh.py]"]
  node_thor_engine["THOR CKKS adapter<br/>[ckks.py]"]
end

subgraph group_crypto["CKKS runtime"]
  node_engine["CKKS engine<br/>[ckks_engine.py]"]
  node_bootstrap["Bootstrapping"]
  node_encdec["Encoding and encryption<br/>[encdec.py]"]
  node_data_struct["Ciphertext structures<br/>[data_struct.py]"]
end

subgraph group_foundation["Crypto foundations"]
  node_context["CKKS parameters<br/>[ckks_context.py]"]
  node_primes["Prime generation<br/>[generate_primes.py]"]
  node_cache[("Prime cache<br/>[cache.py]")]
  node_security["Security parameters"]
  node_ntt["NTT context<br/>[ntt_context.py]"]
  node_rng["Secure randomness<br/>[csprng.py]"]
end

node_user(("Model user"))

node_user -.->|"prepares model"| node_model_encoder
node_user -.->|"runs HE model"| node_bert
node_model_encoder -->|"uses engine"| node_thor_engine
node_bert -->|"uses layers"| node_linear
node_bert -->|"applies GELU"| node_gelu
node_bert -->|"applies softmax"| node_softmax
node_bert -->|"applies normalization"| node_layernorm
node_bert -->|"applies tanh"| node_tanh
node_gelu -->|"evaluates polynomial"| node_polynomial
node_softmax -->|"evaluates polynomial"| node_polynomial
node_tanh -->|"evaluates polynomial"| node_polynomial
node_linear -->|"uses operations"| node_thor_engine
node_thor_engine -->|"extends engine"| node_engine
node_thor_engine -->|"invokes bootstrapping"| node_bootstrap
node_engine -->|"constructs context"| node_context
node_engine -->|"uses transforms"| node_ntt
node_engine -->|"uses encoding"| node_encdec
node_engine -->|"operates on"| node_data_struct
node_engine -->|"uses randomness"| node_rng
node_context -->|"loads primes"| node_primes
node_context -->|"checks security"| node_security
node_context -->|"uses cache"| node_cache
node_cache -->|"generates cache"| node_primes

click node_model_encoder "https://github.com/crypto-starlab/thor/blob/main/src/thor/model_encoder.py"
click node_model_data "https://github.com/crypto-starlab/thor/blob/main/src/thor/data.py"
click node_bert "https://github.com/crypto-starlab/thor/blob/main/src/thor/bert.py"
click node_linear "https://github.com/crypto-starlab/thor/blob/main/src/thor/linear.py"
click node_polynomial "https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/polynomial.py"
click node_softmax "https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/softmax.py"
click node_gelu "https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/gelu.py"
click node_layernorm "https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/layernorm.py"
click node_tanh "https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/tanh.py"
click node_thor_engine "https://github.com/crypto-starlab/thor/blob/main/src/thor/ckks.py"
click node_engine "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/ckks_engine.py"
click node_bootstrap "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/bootstrapping/ckks_bootstrapping.py"
click node_encdec "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/encdec/encdec.py"
click node_data_struct "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/data_struct.py"
click node_context "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/context/ckks_context.py"
click node_primes "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/context/generate_primes.py"
click node_cache "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/cache/cache.py"
click node_security "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/context/security_parameters.py"
click node_ntt "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/ntt/ntt_context.py"
click node_rng "https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/csprng/csprng.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_model_encoder,node_model_data,node_user toneBlue
class node_bert,node_linear,node_polynomial,node_softmax,node_gelu,node_layernorm,node_tanh,node_thor_engine toneAmber
class node_engine,node_bootstrap,node_encdec,node_data_struct toneMint
class node_context,node_primes,node_cache,node_security,node_ntt,node_rng toneRose
```

## Components

### Model preparation

- [Model encoder](https://github.com/crypto-starlab/thor/blob/main/src/thor/model_encoder.py): `src/thor/model_encoder.py`
- [Model data](https://github.com/crypto-starlab/thor/blob/main/src/thor/data.py): `src/thor/data.py`

### Encrypted inference

- [BERT layers](https://github.com/crypto-starlab/thor/blob/main/src/thor/bert.py): `src/thor/bert.py`
- [Linear evaluator](https://github.com/crypto-starlab/thor/blob/main/src/thor/linear.py): `src/thor/linear.py`
- [Polynomial evaluator](https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/polynomial.py): `src/thor/nonlinear/polynomial.py`
- [Encrypted softmax](https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/softmax.py): `src/thor/nonlinear/softmax.py`
- [Encrypted GELU](https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/gelu.py): `src/thor/nonlinear/gelu.py`
- [Encrypted layer norm](https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/layernorm.py): `src/thor/nonlinear/layernorm.py`
- [Encrypted tanh](https://github.com/crypto-starlab/thor/blob/main/src/thor/nonlinear/tanh.py): `src/thor/nonlinear/tanh.py`
- [THOR CKKS adapter](https://github.com/crypto-starlab/thor/blob/main/src/thor/ckks.py): `src/thor/ckks.py`

### CKKS runtime

- [CKKS engine](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/ckks_engine.py): `liberate/src/liberate/fhe/ckks_engine.py`
- [Bootstrapping](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/bootstrapping/ckks_bootstrapping.py): `liberate/src/liberate/fhe/bootstrapping/ckks_bootstrapping.py`
- [Encoding and encryption](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/encdec/encdec.py): `liberate/src/liberate/fhe/encdec/encdec.py`
- [Ciphertext structures](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/data_struct.py): `liberate/src/liberate/fhe/data_struct.py`

### Crypto foundations

- [CKKS parameters](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/context/ckks_context.py): `liberate/src/liberate/fhe/context/ckks_context.py`
- [Prime generation](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/context/generate_primes.py): `liberate/src/liberate/fhe/context/generate_primes.py`
- [Prime cache](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/cache/cache.py): `liberate/src/liberate/fhe/cache/cache.py`
- [Security parameters](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/fhe/context/security_parameters.py): `liberate/src/liberate/fhe/context/security_parameters.py`
- [NTT context](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/ntt/ntt_context.py): `liberate/src/liberate/ntt/ntt_context.py`
- [Secure randomness](https://github.com/crypto-starlab/thor/blob/main/liberate/src/liberate/csprng/csprng.py): `liberate/src/liberate/csprng/csprng.py`

### Other components

- **Model user**

## Connections

- Model user → Model encoder: prepares model
- Model user → BERT layers: runs HE model
- Model encoder → THOR CKKS adapter: uses engine (evidence: `src/thor/model_encoder.py`)
- BERT layers → Linear evaluator: uses layers (evidence: `src/thor/bert.py`)
- BERT layers → Encrypted GELU: applies GELU (evidence: `src/thor/bert.py`)
- BERT layers → Encrypted softmax: applies softmax (evidence: `src/thor/bert.py`)
- BERT layers → Encrypted layer norm: applies normalization (evidence: `src/thor/bert.py`)
- BERT layers → Encrypted tanh: applies tanh (evidence: `src/thor/bert.py`)
- Encrypted GELU → Polynomial evaluator: evaluates polynomial (evidence: `src/thor/nonlinear/gelu.py`)
- Encrypted softmax → Polynomial evaluator: evaluates polynomial (evidence: `src/thor/nonlinear/softmax.py`)
- Encrypted tanh → Polynomial evaluator: evaluates polynomial (evidence: `src/thor/nonlinear/tanh.py`)
- Linear evaluator → THOR CKKS adapter: uses operations (evidence: `src/thor/linear.py`)
- THOR CKKS adapter → CKKS engine: extends engine (evidence: `src/thor/ckks.py`)
- THOR CKKS adapter → Bootstrapping: invokes bootstrapping (evidence: `src/thor/ckks.py`)
- CKKS engine → CKKS parameters: constructs context (evidence: `liberate/src/liberate/fhe/ckks_engine.py`)
- CKKS engine → NTT context: uses transforms (evidence: `liberate/src/liberate/fhe/ckks_engine.py`)
- CKKS engine → Encoding and encryption: uses encoding (evidence: `liberate/src/liberate/fhe/ckks_engine.py`)
- CKKS engine → Ciphertext structures: operates on (evidence: `liberate/src/liberate/fhe/ckks_engine.py`)
- CKKS engine → Secure randomness: uses randomness (evidence: `liberate/src/liberate/fhe/ckks_engine.py`)
- CKKS parameters → Prime generation: loads primes (evidence: `liberate/src/liberate/fhe/context/ckks_context.py`)
- CKKS parameters → Security parameters: checks security (evidence: `liberate/src/liberate/fhe/context/ckks_context.py`)
- CKKS parameters → Prime cache: uses cache (evidence: `liberate/src/liberate/fhe/context/ckks_context.py`)
- Prime cache → Prime generation: generates cache (evidence: `liberate/src/liberate/fhe/cache/cache.py`)