# bgiresearch/biollm architecture

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

- Interactive diagram: https://gitdiagram.com/bgiresearch/biollm
- Repository: https://github.com/bgiresearch/biollm

## Overview

BioLLM is a framework for applying and benchmarking single-cell foundation models through a standardized interface. A researcher selects a task and model; task code uses model loaders and preprocessing/data components to produce analysis outputs, which can be evaluated for relevant tasks. The repository also includes distinct annotation, embedding, integration, perturbation, gene-regulatory-network, and drug-sensitivity capabilities. Edges reflect README claims and visible source-index references; where implementation details were not sampled, relationships are left unconnected or marked unverified.

Main entry points: [`biollm/tasks/bio_task.py`](https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/bio_task.py) (Task interface), [`biollm/loader/scgpt.py`](https://github.com/bgiresearch/biollm/blob/master/biollm/loader/scgpt.py) (scGPT loader), [`biollm/data_preprocess/scgpt_handler.py`](https://github.com/bgiresearch/biollm/blob/master/biollm/data_preprocess/scgpt_handler.py) (scGPT preprocessing), [`biollm/loader/mamba.py`](https://github.com/bgiresearch/biollm/blob/master/biollm/loader/mamba.py) (scMamba loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Tasks and workflows"]
  node_bio_task["Task interface<br/>[bio_task.py]"]
  node_annotation["Cell annotation<br/>[cell_annotation.py]"]
  node_embedding["Cell embedding<br/>[cell_embedding.py]"]
  node_integration["Model integration"]
  node_perturbation["Perturbation tasks"]
  node_grn["Gene regulation<br/>[grn.py]"]
  node_drug["Drug sensitivity"]
end

subgraph group_prep["Data preparation"]
  node_preprocess["Expression preprocessing<br/>[data_handler.py]"]
  node_scgpt_prep["scGPT preprocessing<br/>[scgpt_handler.py]"]
  node_datasets["Single-cell datasets<br/>[sc_dataset.py]"]
  node_tokenizer["Gene tokenization<br/>[gene_tokenizer.py]"]
end

subgraph group_models["Model integration"]
  node_loaders["Model loaders<br/>[loader_base.py]"]
  node_scgpt_loader["scGPT loader<br/>[scgpt.py]"]
  node_mamba_loader["scMamba loader<br/>[mamba.py]"]
  node_scgpt_model["scGPT models<br/>[model.py]"]
  node_scgpt_multiomic["Multi-omic model<br/>[multiomic_model.py]"]
  node_mamba_model["Mamba model<br/>[mambaLM.py]"]
  node_gears["GEARS perturbation<br/>[gears.py]"]
  node_scfoundation["scFoundation embeddings<br/>[load.py]"]
end

subgraph group_analysis["Analysis and evaluation"]
  node_evaluation["Benchmark metrics"]
end

subgraph group_runtime["Shared runtime"]
  node_trainer["Training runtime<br/>[trainer.py]"]
  node_scmamba_data["scMamba data pipeline<br/>[dataset.py]"]
  node_logging["Logging<br/>[log_manager.py]"]
end

node_researcher(("Researcher"))
node_result["Analysis results"]

node_researcher -->|"selects task"| node_bio_task
node_bio_task -->|"loads model"| node_scgpt_loader
node_bio_task -->|"loads model"| node_mamba_loader
node_bio_task -->|"selects loader"| node_loaders
node_scgpt_loader -->|"extends"| node_loaders
node_mamba_loader -->|"extends"| node_loaders
node_scgpt_loader -->|"preprocesses data"| node_scgpt_prep
node_scgpt_prep -->|"uses"| node_preprocess
node_scgpt_prep -->|"creates dataset"| node_datasets
node_scgpt_prep -->|"tokenizes genes"| node_tokenizer
node_preprocess -->|"loads vocabulary"| node_tokenizer
node_scgpt_loader -->|"constructs model"| node_scgpt_model
node_scgpt_loader -->|"imports model"| node_scgpt_multiomic
node_mamba_loader -->|"constructs model"| node_mamba_model
node_embedding -->|"uses interface"| node_bio_task
node_embedding -->|"evaluates embeddings"| node_evaluation
node_evaluation -.->|"returns metrics"| node_result
node_perturbation -.->|"uses backend"| node_gears
node_perturbation -.->|"produces predictions"| node_result
node_integration -.->|"produces integration"| node_result
node_annotation -.->|"produces labels"| node_result
node_grn -.->|"produces networks"| node_result
node_drug -.->|"produces predictions"| node_result
node_mamba_loader -->|"prepares cell data"| node_scmamba_data
node_bio_task -->|"uses logging"| node_logging
node_trainer -.->|"uses metrics"| node_evaluation
node_researcher -.->|"requests analysis"| node_annotation
node_researcher -.->|"requests analysis"| node_embedding
node_researcher -.->|"requests analysis"| node_integration
node_researcher -.->|"requests analysis"| node_perturbation
node_researcher -.->|"requests analysis"| node_grn
node_researcher -.->|"requests analysis"| node_drug

click node_bio_task "https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/bio_task.py"
click node_annotation "https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/cell_annotation.py"
click node_embedding "https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/cell_embedding.py"
click node_integration "https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/integration/intergration_task_scgpt.py"
click node_perturbation "https://github.com/bgiresearch/biollm/tree/master/biollm/tasks/perturbation"
click node_grn "https://github.com/bgiresearch/biollm/blob/master/biollm/algorithm/grn.py"
click node_drug "https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/drug_sensitivity.py"
click node_preprocess "https://github.com/bgiresearch/biollm/blob/master/biollm/data_preprocess/data_handler.py"
click node_scgpt_prep "https://github.com/bgiresearch/biollm/blob/master/biollm/data_preprocess/scgpt_handler.py"
click node_datasets "https://github.com/bgiresearch/biollm/blob/master/biollm/dataset/sc_dataset.py"
click node_tokenizer "https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scgpt/tokenizer/gene_tokenizer.py"
click node_loaders "https://github.com/bgiresearch/biollm/blob/master/biollm/loader/loader_base.py"
click node_scgpt_loader "https://github.com/bgiresearch/biollm/blob/master/biollm/loader/scgpt.py"
click node_mamba_loader "https://github.com/bgiresearch/biollm/blob/master/biollm/loader/mamba.py"
click node_scgpt_model "https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scgpt/model/model.py"
click node_scgpt_multiomic "https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scgpt/model/multiomic_model.py"
click node_mamba_model "https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scmamba/scmamba/mambaLM.py"
click node_gears "https://github.com/bgiresearch/biollm/blob/master/biollm/repo/gears/gears.py"
click node_scfoundation "https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scfoundation/load.py"
click node_trainer "https://github.com/bgiresearch/biollm/blob/master/biollm/trainer/trainer.py"
click node_scmamba_data "https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scmamba/scLLM_utils/dataset.py"
click node_logging "https://github.com/bgiresearch/biollm/blob/master/biollm/utils/log_manager.py"
click node_evaluation "https://github.com/bgiresearch/biollm/blob/master/biollm/evaluate/bm_cell_embedding.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_bio_task,node_annotation,node_embedding,node_integration,node_perturbation,node_grn,node_drug toneBlue
class node_preprocess,node_scgpt_prep,node_datasets,node_tokenizer toneAmber
class node_loaders,node_scgpt_loader,node_mamba_loader,node_scgpt_model,node_scgpt_multiomic,node_mamba_model,node_gears,node_scfoundation toneMint
class node_evaluation toneRose
class node_trainer,node_scmamba_data,node_logging,node_researcher,node_result toneIndigo
```

## Components

### Tasks and workflows

- [Task interface](https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/bio_task.py): `biollm/tasks/bio_task.py`
- [Cell annotation](https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/cell_annotation.py): `biollm/tasks/cell_annotation.py`
- [Cell embedding](https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/cell_embedding.py): `biollm/tasks/cell_embedding.py`
- [Model integration](https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/integration/intergration_task_scgpt.py): `biollm/tasks/integration/intergration_task_scgpt.py`
- [Perturbation tasks](https://github.com/bgiresearch/biollm/tree/master/biollm/tasks/perturbation): `biollm/tasks/perturbation`
- [Gene regulation](https://github.com/bgiresearch/biollm/blob/master/biollm/algorithm/grn.py): `biollm/algorithm/grn.py`
- [Drug sensitivity](https://github.com/bgiresearch/biollm/blob/master/biollm/tasks/drug_sensitivity.py): `biollm/tasks/drug_sensitivity.py`

### Data preparation

- [Expression preprocessing](https://github.com/bgiresearch/biollm/blob/master/biollm/data_preprocess/data_handler.py): `biollm/data_preprocess/data_handler.py`
- [scGPT preprocessing](https://github.com/bgiresearch/biollm/blob/master/biollm/data_preprocess/scgpt_handler.py): `biollm/data_preprocess/scgpt_handler.py`
- [Single-cell datasets](https://github.com/bgiresearch/biollm/blob/master/biollm/dataset/sc_dataset.py): `biollm/dataset/sc_dataset.py`
- [Gene tokenization](https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scgpt/tokenizer/gene_tokenizer.py): `biollm/repo/scgpt/tokenizer/gene_tokenizer.py`

### Model integration

- [Model loaders](https://github.com/bgiresearch/biollm/blob/master/biollm/loader/loader_base.py): `biollm/loader/loader_base.py`
- [scGPT loader](https://github.com/bgiresearch/biollm/blob/master/biollm/loader/scgpt.py): `biollm/loader/scgpt.py`
- [scMamba loader](https://github.com/bgiresearch/biollm/blob/master/biollm/loader/mamba.py): `biollm/loader/mamba.py`
- [scGPT models](https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scgpt/model/model.py): `biollm/repo/scgpt/model/model.py`
- [Multi-omic model](https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scgpt/model/multiomic_model.py): `biollm/repo/scgpt/model/multiomic_model.py`
- [Mamba model](https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scmamba/scmamba/mambaLM.py): `biollm/repo/scmamba/scmamba/mambaLM.py`
- [GEARS perturbation](https://github.com/bgiresearch/biollm/blob/master/biollm/repo/gears/gears.py): `biollm/repo/gears/gears.py`
- [scFoundation embeddings](https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scfoundation/load.py): `biollm/repo/scfoundation/load.py`

### Analysis and evaluation

- [Benchmark metrics](https://github.com/bgiresearch/biollm/blob/master/biollm/evaluate/bm_cell_embedding.py): `biollm/evaluate/bm_cell_embedding.py`

### Shared runtime

- [Training runtime](https://github.com/bgiresearch/biollm/blob/master/biollm/trainer/trainer.py): `biollm/trainer/trainer.py`
- [scMamba data pipeline](https://github.com/bgiresearch/biollm/blob/master/biollm/repo/scmamba/scLLM_utils/dataset.py): `biollm/repo/scmamba/scLLM_utils/dataset.py`
- [Logging](https://github.com/bgiresearch/biollm/blob/master/biollm/utils/log_manager.py): `biollm/utils/log_manager.py`

### Other components

- **Researcher**
- **Analysis results**

## Connections

- Researcher → Task interface: selects task (evidence: `README.md`)
- Task interface → scGPT loader: loads model (evidence: `biollm/tasks/bio_task.py`)
- Task interface → scMamba loader: loads model (evidence: `biollm/tasks/bio_task.py`)
- Task interface → Model loaders: selects loader (evidence: `biollm/tasks/bio_task.py`)
- scGPT loader → Model loaders: extends (evidence: `biollm/loader/scgpt.py`)
- scMamba loader → Model loaders: extends (evidence: `biollm/loader/mamba.py`)
- scGPT loader → scGPT preprocessing: preprocesses data (evidence: `biollm/loader/scgpt.py`)
- scGPT preprocessing → Expression preprocessing: uses (evidence: `biollm/data_preprocess/scgpt_handler.py`)
- scGPT preprocessing → Single-cell datasets: creates dataset (evidence: `biollm/data_preprocess/scgpt_handler.py`)
- scGPT preprocessing → Gene tokenization: tokenizes genes (evidence: `biollm/data_preprocess/scgpt_handler.py`)
- Expression preprocessing → Gene tokenization: loads vocabulary (evidence: `biollm/data_preprocess/data_handler.py`)
- scGPT loader → scGPT models: constructs model (evidence: `biollm/loader/scgpt.py`)
- scGPT loader → Multi-omic model: imports model
- scMamba loader → Mamba model: constructs model (evidence: `biollm/loader/mamba.py`)
- Cell embedding → Task interface: uses interface (evidence: `biollm/tasks/cell_embedding.py`)
- Cell embedding → Benchmark metrics: evaluates embeddings (evidence: `biollm/tasks/cell_embedding.py`)
- Benchmark metrics → Analysis results: returns metrics
- Perturbation tasks → GEARS perturbation: uses backend
- Perturbation tasks → Analysis results: produces predictions
- Model integration → Analysis results: produces integration
- Cell annotation → Analysis results: produces labels
- Gene regulation → Analysis results: produces networks
- Drug sensitivity → Analysis results: produces predictions
- scMamba loader → scMamba data pipeline: prepares cell data (evidence: `biollm/loader/mamba.py`)
- Task interface → Logging: uses logging (evidence: `biollm/tasks/bio_task.py`)
- Training runtime → Benchmark metrics: uses metrics
- Researcher → Cell annotation: requests analysis (evidence: `README.md`)
- Researcher → Cell embedding: requests analysis (evidence: `README.md`)
- Researcher → Model integration: requests analysis (evidence: `README.md`)
- Researcher → Perturbation tasks: requests analysis (evidence: `README.md`)
- Researcher → Gene regulation: requests analysis (evidence: `README.md`)
- Researcher → Drug sensitivity: requests analysis (evidence: `README.md`)
