# vt-asaplab/zip architecture

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

- Interactive diagram: https://gitdiagram.com/vt-asaplab/zip
- Repository: https://github.com/vt-asaplab/zip

## Overview

ZIP is a research prototype for high-precision zero-knowledge AI inference. The documented workflow combines neural-network inference workloads with precomputed piecewise-polynomial approximations and proof-generation components: linear PLONK circuits use zk-Location, while nonlinear circuits and a multi-lookup argument are part of ZIP. The graph also shows NFGen’s documented generator dependencies and Caulk’s single- and multi-opening code. Several subsystem links come from the README; unsampled source is represented at directory level where implementation details are uncertain.

Main entry points: [`src/piecewise_polynomial_approximation/NFGen/src/NFGen/main.py`](https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/main.py) (NFGen generator), [`src/proof_generation/caulk/src/multi/unity.rs`](https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/multi/unity.rs) (Multi lookup), [`src/piecewise_polynomial_approximation/approx.py`](https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/approx.py) (Approximation driver), [`src/proof_generation/caulk/src/single/unity.rs`](https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/single/unity.rs) (Single lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workloads["Inference workloads"]
  node_lenet["LeNet workload<br/>[infer_lenet.py]"]
  node_utkface["UTKFace CNN<br/>[CNN_MAE.py]"]
  node_minibert["miniBERT workload<br/>[minibert.py]"]
end

subgraph group_approximation["Polynomial approximation"]
  node_approx_driver["Approximation driver<br/>[approx.py]"]
  node_nfgen_main["NFGen generator<br/>[main.py]"]
  node_nfgen_fit["Polynomial fitting<br/>[fitter.py]"]
  node_nfgen_analysis["Fit analysis<br/>[analysis.py]"]
  node_nfgen_funcs["Function utilities<br/>[funcs.py]"]
  node_nfgen_codegen["Code generation<br/>[code_generator.py]"]
  node_poly_tables["Activation tables<br/>[elu_approx.py]"]
end

subgraph group_proof["Proof generation"]
  node_linear_circuit["Linear circuits<br/>[main.go]"]
  node_nonlinear_circuit["Nonlinear circuits<br/>[main.go]"]
  node_zip_lookup["ZIP multi-lookup"]
  node_zk_location["IEEE linear proofs"]
end

subgraph group_protocols["Proof protocols"]
  node_caulk_single["Single lookup<br/>[unity.rs]"]
  node_caulk_multi["Multi lookup<br/>[unity.rs]"]
  node_caulk_setup["Lookup setup<br/>[setup.rs]"]
  node_caulk_kzg["KZG backend<br/>[kzg.rs]"]
end

node_user(("Research user"))

node_user -->|"runs inference"| node_lenet
node_user -->|"runs inference"| node_utkface
node_user -->|"runs inference"| node_minibert
node_approx_driver -->|"invokes generator"| node_nfgen_main
node_nfgen_main -->|"uses fitting"| node_nfgen_fit
node_nfgen_main -->|"uses functions"| node_nfgen_funcs
node_nfgen_main -->|"uses analysis"| node_nfgen_analysis
node_nfgen_main -->|"uses generator"| node_nfgen_codegen
node_utkface -->|"imports approximation"| node_poly_tables
node_approx_driver -->|"generates approximations"| node_poly_tables
node_user -->|"proves inference"| node_linear_circuit
node_user -->|"proves inference"| node_nonlinear_circuit
node_linear_circuit -->|"uses linear proofs"| node_zk_location
node_nonlinear_circuit -->|"uses lookup argument"| node_zip_lookup
node_zip_lookup -->|"integrates multi-lookup"| node_caulk_multi
node_caulk_multi -->|"uses setup"| node_caulk_setup
node_caulk_multi -->|"uses commitments"| node_caulk_kzg
node_caulk_single -->|"uses setup"| node_caulk_setup
node_caulk_single -->|"uses commitments"| node_caulk_kzg

click node_lenet "https://github.com/vt-asaplab/zip/blob/main/src/CNN/LeNet/infer_lenet.py"
click node_utkface "https://github.com/vt-asaplab/zip/blob/main/src/CNN/UTKFace_MAE/CNN_MAE.py"
click node_minibert "https://github.com/vt-asaplab/zip/blob/main/src/LLM/miniBERT/minibert.py"
click node_approx_driver "https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/approx.py"
click node_nfgen_main "https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/main.py"
click node_nfgen_fit "https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/fitter.py"
click node_nfgen_analysis "https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/analysis.py"
click node_nfgen_funcs "https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/funcs.py"
click node_nfgen_codegen "https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/code_generator.py"
click node_poly_tables "https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/precomputed_lookup_tables_ieee754/elu_approx.py"
click node_linear_circuit "https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/ZIP_proof_generation/ZIP_circuit/circuit/linear/main.go"
click node_nonlinear_circuit "https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/ZIP_proof_generation/ZIP_circuit/circuit/non-linear/main.go"
click node_zip_lookup "https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/ZIP_proof_generation/ZIP_lookup/add_interval_index.py"
click node_zk_location "https://github.com/vt-asaplab/zip/tree/main/src/proof_generation/zk-Location"
click node_caulk_single "https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/single/unity.rs"
click node_caulk_multi "https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/multi/unity.rs"
click node_caulk_setup "https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/multi/setup.rs"
click node_caulk_kzg "https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/kzg.rs"

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_lenet,node_utkface,node_minibert,node_user toneBlue
class node_approx_driver,node_nfgen_main,node_nfgen_fit,node_nfgen_analysis,node_nfgen_funcs,node_nfgen_codegen,node_poly_tables toneAmber
class node_linear_circuit,node_nonlinear_circuit,node_zip_lookup,node_zk_location toneMint
class node_caulk_single,node_caulk_multi,node_caulk_setup,node_caulk_kzg toneRose
```

## Components

### Inference workloads

- [LeNet workload](https://github.com/vt-asaplab/zip/blob/main/src/CNN/LeNet/infer_lenet.py): `src/CNN/LeNet/infer_lenet.py`
- [UTKFace CNN](https://github.com/vt-asaplab/zip/blob/main/src/CNN/UTKFace_MAE/CNN_MAE.py): `src/CNN/UTKFace_MAE/CNN_MAE.py`
- [miniBERT workload](https://github.com/vt-asaplab/zip/blob/main/src/LLM/miniBERT/minibert.py): `src/LLM/miniBERT/minibert.py`

### Polynomial approximation

- [Approximation driver](https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/approx.py): `src/piecewise_polynomial_approximation/approx.py`
- [NFGen generator](https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/main.py): `src/piecewise_polynomial_approximation/NFGen/src/NFGen/main.py`
- [Polynomial fitting](https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/fitter.py): `src/piecewise_polynomial_approximation/NFGen/src/NFGen/fitter.py`
- [Fit analysis](https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/analysis.py): `src/piecewise_polynomial_approximation/NFGen/src/NFGen/analysis.py`
- [Function utilities](https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/funcs.py): `src/piecewise_polynomial_approximation/NFGen/src/NFGen/funcs.py`
- [Code generation](https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/NFGen/src/NFGen/code_generator.py): `src/piecewise_polynomial_approximation/NFGen/src/NFGen/code_generator.py`
- [Activation tables](https://github.com/vt-asaplab/zip/blob/main/src/piecewise_polynomial_approximation/precomputed_lookup_tables_ieee754/elu_approx.py): `src/piecewise_polynomial_approximation/precomputed_lookup_tables_ieee754/elu_approx.py`

### Proof generation

- [Linear circuits](https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/ZIP_proof_generation/ZIP_circuit/circuit/linear/main.go): `src/proof_generation/ZIP_proof_generation/ZIP_circuit/circuit/linear/main.go`
- [Nonlinear circuits](https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/ZIP_proof_generation/ZIP_circuit/circuit/non-linear/main.go): `src/proof_generation/ZIP_proof_generation/ZIP_circuit/circuit/non-linear/main.go`
- [ZIP multi-lookup](https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/ZIP_proof_generation/ZIP_lookup/add_interval_index.py): `src/proof_generation/ZIP_proof_generation/ZIP_lookup/add_interval_index.py`
- [IEEE linear proofs](https://github.com/vt-asaplab/zip/tree/main/src/proof_generation/zk-Location): `src/proof_generation/zk-Location`

### Proof protocols

- [Single lookup](https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/single/unity.rs): `src/proof_generation/caulk/src/single/unity.rs`
- [Multi lookup](https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/multi/unity.rs): `src/proof_generation/caulk/src/multi/unity.rs`
- [Lookup setup](https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/multi/setup.rs): `src/proof_generation/caulk/src/multi/setup.rs`
- [KZG backend](https://github.com/vt-asaplab/zip/blob/main/src/proof_generation/caulk/src/kzg.rs): `src/proof_generation/caulk/src/kzg.rs`

### Other components

- **Research user**

## Connections

- Research user → LeNet workload: runs inference (evidence: `README.md`)
- Research user → UTKFace CNN: runs inference (evidence: `README.md`)
- Research user → miniBERT workload: runs inference (evidence: `README.md`)
- Approximation driver → NFGen generator: invokes generator (evidence: `src/piecewise_polynomial_approximation/approx.py`)
- NFGen generator → Polynomial fitting: uses fitting (evidence: `src/piecewise_polynomial_approximation/NFGen/src/NFGen/main.py`)
- NFGen generator → Function utilities: uses functions (evidence: `src/piecewise_polynomial_approximation/NFGen/src/NFGen/main.py`)
- NFGen generator → Fit analysis: uses analysis (evidence: `src/piecewise_polynomial_approximation/NFGen/src/NFGen/main.py`)
- NFGen generator → Code generation: uses generator (evidence: `src/piecewise_polynomial_approximation/NFGen/src/NFGen/main.py`)
- UTKFace CNN → Activation tables: imports approximation (evidence: `src/CNN/UTKFace_MAE/CNN_MAE.py`)
- Approximation driver → Activation tables: generates approximations (evidence: `src/piecewise_polynomial_approximation/approx.py`)
- Research user → Linear circuits: proves inference (evidence: `README.md`)
- Research user → Nonlinear circuits: proves inference (evidence: `README.md`)
- Linear circuits → IEEE linear proofs: uses linear proofs (evidence: `README.md`)
- Nonlinear circuits → ZIP multi-lookup: uses lookup argument (evidence: `README.md`)
- ZIP multi-lookup → Multi lookup: integrates multi-lookup (evidence: `README.md`)
- Multi lookup → Lookup setup: uses setup (evidence: `src/proof_generation/caulk/src/multi/mod.rs`)
- Multi lookup → KZG backend: uses commitments (evidence: `src/proof_generation/caulk/src/multi/mod.rs`)
- Single lookup → Lookup setup: uses setup
- Single lookup → KZG backend: uses commitments (evidence: `src/proof_generation/caulk/src/single/unity.rs`)
