# izgys/enzyme-llm-platform architecture

> Architecture diagram of the GitHub repository izgys/enzyme-llm-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/izgys/enzyme-llm-platform
- Repository: https://github.com/izgys/enzyme-llm-platform

## Overview

This is an enzyme EC-subclass classifier built around ESM-2 fine-tuning with LoRA and homology-aware evaluation. Its principal workflow downloads and curates Swiss-Prot sequences, creates cluster-separated splits, trains and evaluates a classifier, then calibrates confidence for prediction. Interpretability, structure mapping, visualization, and experiment tracking are additional documented capabilities. Source excerpts substantiate the data pipeline and dataset layer; several model-serving and analysis modules are represented from README claims and tree paths, so their internal wiring is intentionally limited.

Main entry points: [`src/interpretability`](https://github.com/izgys/enzyme-llm-platform/tree/main/src/interpretability) (Integrated gradients), [`src/model`](https://github.com/izgys/enzyme-llm-platform/tree/main/src/model) (ESM-2 classifier), [`src/data/clustering.py`](https://github.com/izgys/enzyme-llm-platform/blob/main/src/data/clustering.py) (Homology splitting), [`src/training`](https://github.com/izgys/enzyme-llm-platform/tree/main/src/training) (LoRA fine-tuning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_download["Fetch and filter<br/>[download.py]"]
  node_raw["Raw records"]
  node_preprocess["Clean and label<br/>[preprocess.py]"]
  node_processed["Processed records"]
  node_cluster["Homology splitting<br/>[clustering.py]"]
  node_splits["Train val test"]
  node_dataset["Tokenized batches<br/>[dataset.py]"]
end

subgraph group_learning["Model learning"]
  node_training["LoRA fine-tuning"]
  node_model["ESM-2 classifier"]
  node_baseline["Zero-shot baseline<br/>[run_baseline.py]"]
  node_calibration["Confidence calibration"]
end

subgraph group_serving["Prediction"]
  node_inference["Inference endpoint"]
end

subgraph group_analysis["Interpretation"]
  node_interpretability["Integrated gradients"]
  node_msa["MSA conservation"]
  node_structure["PDB mapping"]
  node_visualisation["Result visualization"]
end

subgraph group_operations["Experiment operations"]
  node_mlflow[("MLflow tracking")]
end

node_uniprot(("Swiss-Prot"))
node_mmseqs["MMseqs2"]
node_client(("Prediction client"))

node_uniprot -->|"provides entries"| node_download
node_download -->|"writes records"| node_raw
node_raw -->|"loads records"| node_preprocess
node_preprocess -->|"writes labels"| node_processed
node_processed -->|"loads records"| node_cluster
node_cluster -->|"runs clustering"| node_mmseqs
node_cluster -->|"writes splits"| node_splits
node_splits -->|"loads sequences"| node_dataset
node_dataset -->|"supplies batches"| node_training
node_training -->|"fine-tunes"| node_model
node_model -->|"supplies logits"| node_calibration
node_calibration -->|"calibrates scores"| node_inference
node_client -->|"requests prediction"| node_inference
node_inference -->|"predicts with"| node_model
node_model -->|"attributes predictions"| node_interpretability
node_interpretability -->|"cross-checks conservation"| node_msa
node_interpretability -->|"maps scores"| node_structure
node_interpretability -->|"provides attributions"| node_visualisation
node_training -.->|"tracks runs"| node_mlflow
node_baseline -->|"evaluates embeddings"| node_splits

click node_download "https://github.com/izgys/enzyme-llm-platform/blob/main/src/data/download.py"
click node_raw "https://github.com/izgys/enzyme-llm-platform/tree/main/data/raw"
click node_preprocess "https://github.com/izgys/enzyme-llm-platform/blob/main/src/data/preprocess.py"
click node_processed "https://github.com/izgys/enzyme-llm-platform/tree/main/data/processed"
click node_cluster "https://github.com/izgys/enzyme-llm-platform/blob/main/src/data/clustering.py"
click node_splits "https://github.com/izgys/enzyme-llm-platform/tree/main/data/processed"
click node_dataset "https://github.com/izgys/enzyme-llm-platform/blob/main/src/data/dataset.py"
click node_training "https://github.com/izgys/enzyme-llm-platform/tree/main/src/training"
click node_model "https://github.com/izgys/enzyme-llm-platform/tree/main/src/model"
click node_baseline "https://github.com/izgys/enzyme-llm-platform/blob/main/experiments/baseline_zeroshot/run_baseline.py"
click node_calibration "https://github.com/izgys/enzyme-llm-platform/tree/main/src/calibration"
click node_inference "https://github.com/izgys/enzyme-llm-platform/tree/main/src/inference"
click node_interpretability "https://github.com/izgys/enzyme-llm-platform/tree/main/src/interpretability"
click node_structure "https://github.com/izgys/enzyme-llm-platform/tree/main/src/interpretability"
click node_visualisation "https://github.com/izgys/enzyme-llm-platform/tree/main/src/visualisation"

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_download,node_raw,node_preprocess,node_processed,node_cluster,node_splits,node_dataset,node_client toneBlue
class node_training,node_model,node_baseline,node_calibration toneAmber
class node_inference toneMint
class node_interpretability,node_msa,node_structure,node_visualisation toneRose
class node_mlflow,node_uniprot,node_mmseqs toneIndigo
```

## Components

### Data preparation

- [Fetch and filter](https://github.com/izgys/enzyme-llm-platform/blob/main/src/data/download.py): `src/data/download.py`
- [Raw records](https://github.com/izgys/enzyme-llm-platform/tree/main/data/raw): `data/raw`
- [Clean and label](https://github.com/izgys/enzyme-llm-platform/blob/main/src/data/preprocess.py): `src/data/preprocess.py`
- [Processed records](https://github.com/izgys/enzyme-llm-platform/tree/main/data/processed): `data/processed`
- [Homology splitting](https://github.com/izgys/enzyme-llm-platform/blob/main/src/data/clustering.py): `src/data/clustering.py`
- [Train val test](https://github.com/izgys/enzyme-llm-platform/tree/main/data/processed): `data/processed`
- [Tokenized batches](https://github.com/izgys/enzyme-llm-platform/blob/main/src/data/dataset.py): `src/data/dataset.py`

### Model learning

- [LoRA fine-tuning](https://github.com/izgys/enzyme-llm-platform/tree/main/src/training): `src/training`
- [ESM-2 classifier](https://github.com/izgys/enzyme-llm-platform/tree/main/src/model): `src/model`
- [Zero-shot baseline](https://github.com/izgys/enzyme-llm-platform/blob/main/experiments/baseline_zeroshot/run_baseline.py): `experiments/baseline_zeroshot/run_baseline.py`
- [Confidence calibration](https://github.com/izgys/enzyme-llm-platform/tree/main/src/calibration): `src/calibration`

### Prediction

- [Inference endpoint](https://github.com/izgys/enzyme-llm-platform/tree/main/src/inference): `src/inference`

### Interpretation

- [Integrated gradients](https://github.com/izgys/enzyme-llm-platform/tree/main/src/interpretability): `src/interpretability`
- **MSA conservation**
- [PDB mapping](https://github.com/izgys/enzyme-llm-platform/tree/main/src/interpretability): `src/interpretability`
- [Result visualization](https://github.com/izgys/enzyme-llm-platform/tree/main/src/visualisation): `src/visualisation`

### Experiment operations

- **MLflow tracking**

### Other components

- **Swiss-Prot**
- **MMseqs2**
- **Prediction client**

## Connections

- Swiss-Prot → Fetch and filter: provides entries
- Fetch and filter → Raw records: writes records
- Raw records → Clean and label: loads records
- Clean and label → Processed records: writes labels
- Processed records → Homology splitting: loads records
- Homology splitting → MMseqs2: runs clustering
- Homology splitting → Train val test: writes splits
- Train val test → Tokenized batches: loads sequences
- Tokenized batches → LoRA fine-tuning: supplies batches
- LoRA fine-tuning → ESM-2 classifier: fine-tunes
- ESM-2 classifier → Confidence calibration: supplies logits
- Confidence calibration → Inference endpoint: calibrates scores
- Prediction client → Inference endpoint: requests prediction
- Inference endpoint → ESM-2 classifier: predicts with
- ESM-2 classifier → Integrated gradients: attributes predictions
- Integrated gradients → MSA conservation: cross-checks conservation
- Integrated gradients → PDB mapping: maps scores
- Integrated gradients → Result visualization: provides attributions
- LoRA fine-tuning → MLflow tracking: tracks runs
- Zero-shot baseline → Train val test: evaluates embeddings