# bowang-lab/bioreason architecture

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

- Interactive diagram: https://gitdiagram.com/bowang-lab/bioreason
- Repository: https://github.com/bowang-lab/bioreason

## Overview

1. **What this repo is**
   BioReason is a research codebase for a **DNA-LLM multimodal system** that combines a DNA foundation model with a language model to perform biological reasoning, plus training/evaluation code for both supervised fine-tuning and reinforcement learning.

2. **Top-level execution paths**
   The main runnable entrypoints are separate scripts for each stage: `train_dna_only.py`, `train_dna_qwen.py`, `train_grpo.py`, `reason.py`, and `eval_kegg_dna_vllm.py`. This suggests a pipeline of **train DNA encoder → train DNA+LLM model → optionally RL-tune with GRPO → run inference/evaluation**.

3. **Data subsystem**
   `bioreason/dataset/` contains dataset loaders and preprocessing for the two benchmark families described in the README:
   - `kegg.py` for KEGG-derived reasoning data
   - `variant_effect.py` for coding and non-SNV variant effect data
   - `utils.py` for shared dataset logic  
   The `data/` folder contains notebooks used to curate and inspect datasets, indicating that some dataset creation happens offline and is not part of the runtime training path.

4. **Biological sequence handling**
   `bioreason/dna_modules/` and `bioreason/utils/dna_utils.py` define the DNA-side abstractions. This is the boundary where raw nucleotide sequences are normalized, encoded, and turned into model-ready inputs before they are passed into the language-model side.

5. **Model layer structure**
   `bioreason/models/` is split into several model families:
   - `dna_only.py`: standalone DNA foundation model baseline
   - `dna_llm.py`: the multimodal DNA+LLM architecture
   - `dna_vllm.py`: inference-oriented DNA/LLM integration for fast generation
   - `evo2_tokenizer.py`: tokenizer support for Evo2-style DNA modeling  
   This separation indicates the repo supports both **single-modality baselines** and the **hybrid reasoning model**.

6. **LLM integration and preprocessing**
   `bioreason/models/dl/` contains `processing_dl.py` and `chat_template_dl.py`, which likely adapt biological inputs into the chat / instruction format expected by the chosen LLM. This is the key bridge between structured DNA features and text-generation reasoning.

7. **Training architecture**
   `bioreason/trainer/` holds the RL training stack:
   - `grpo_config.py` for hyperparameters / training settings
   - `grpo_trainer.py` for the GRPO reinforcement-learning loop  
   The presence of GRPO and LoRA artifacts in the repo suggests training is optimized for **parameter-efficient fine-tuning**, not full-model retraining.

8. **Checkpointing and conversion**
   `bioreason/utils/save_ckpt_dna.py`, `save_grpo_ckpt.py`, and the shell scripts `sh_convert_deepspeed_to_hf_ckpt_dna.sh` and `sh_convert_grpo_to_hf_ckpt.sh` show a clear separation between:
   - distributed training checkpoints
   - Hugging Face–style exportable checkpoints  
   This is an important architectural boundary: training uses distributed systems, while inference/export uses normalized model checkpoints.

9. **Inference and evaluation flow**
   `reason.py` is the likely general inference entrypoint, while `eval_kegg_dna_vllm.py` is a specialized evaluator for KEGG-style benchmarks. The `vllm_utils.py` helper indicates the repo uses **vLLM** for efficient batched generation during evaluation or deployment.

10. **Training infrastructure**
    The presence of `ds_config_stage2.json`, `grpo_trainer_lora_model/`, and shell scripts like `sh_grpo.sh`, `sh_train_dna_only.sh`, and `sh_train_dna_qwen.sh` indicates the project relies on **DeepSpeed**, **LoRA adapters**, and GPU-backed training. Architecture-wise, this is a multi-stage distributed ML system rather than a simple single-process model script.

11. **External data/model ecosystem**
    The README and file layout imply heavy use of the **Hugging Face ecosystem** for datasets, models, and checkpoint sharing, plus pretrained DNA and LLM backbones such as **NT, Evo2, and Qwen3**. These are treated as external foundations plugged into BioReason rather than code implemented in-repo.

12. **Practical diagram boundaries**
    An accurate architecture diagram should show four main layers:
    - **data curation / benchmark preparation**
    - **DNA encoding and tokenization**
    - **multimodal model assembly and training**
    - **inference/evaluation + checkpoint conversion**  
    The core innovation is the bridge from DNA representation into the LLM reasoning stack, with GRPO as an optional second-stage alignment mechanism.

Main entry points: [`bioreason/models/dna_llm.py`](https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dna_llm.py) (DNA-LLM), [`bioreason/dna_modules/dna_module.py`](https://github.com/bowang-lab/bioreason/blob/main/bioreason/dna_modules/dna_module.py) (DNA module), [`bioreason/trainer/grpo_trainer.py`](https://github.com/bowang-lab/bioreason/blob/main/bioreason/trainer/grpo_trainer.py) (GRPO trainer), [`bioreason/models/dna_vllm.py`](https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dna_vllm.py) (DNA vLLM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_data["Data curation"]
  node_n_dataset_kegg["KEGG data<br/>dataset loader<br/>[kegg.py]"]
  node_n_dataset_variant["Variant effects<br/>dataset loader<br/>[variant_effect.py]"]
  node_n_dataset_utils["Dataset utils<br/>shared dataset code<br/>[utils.py]"]
  node_n_notebooks["Curation notebooks<br/>offline curation<br/>[README.md]"]
end

subgraph group_g_dna["DNA pipeline"]
  node_n_dna_module["DNA module<br/>sequence encoder<br/>[dna_module.py]"]
  node_n_nucleotide_module["Nucleotide module<br/>sequence frontend"]
  node_n_dna_utils["DNA utils<br/>sequence utilities<br/>[dna_utils.py]"]
end

subgraph group_g_model["Modeling"]
  node_n_dna_only["DNA only<br/>baseline model<br/>[dna_only.py]"]
  node_n_dna_llm["DNA-LLM<br/>multimodal model<br/>[dna_llm.py]"]
  node_n_dna_vllm["DNA vLLM<br/>inference model<br/>[dna_vllm.py]"]
  node_n_dl_processing["DL processing<br/>prompt adapter<br/>[processing_dl.py]"]
  node_n_dl_chat["DL chat template<br/>template adapter"]
end

subgraph group_g_train["Training"]
  node_n_grpo_trainer["GRPO trainer<br/>rl loop<br/>[grpo_trainer.py]"]
  node_n_grpo_config["GRPO config<br/>training config<br/>[grpo_config.py]"]
  node_n_train_dna_only["Train DNA<br/>entrypoint<br/>[train_dna_only.py]"]
  node_n_train_dna_qwen["Train DNA-Qwen<br/>entrypoint<br/>[train_dna_qwen.py]"]
  node_n_train_grpo["Train GRPO<br/>entrypoint<br/>[train_grpo.py]"]
end

subgraph group_g_infer["Inference"]
  node_n_reason["Reason<br/>inference entrypoint<br/>[reason.py]"]
  node_n_eval["KEGG eval<br/>benchmark eval"]
  node_n_save_dna["Save DNA ckpt<br/>checkpoint export<br/>[save_ckpt_dna.py]"]
  node_n_save_grpo["Save GRPO ckpt<br/>checkpoint export<br/>[save_grpo_ckpt.py]"]
  node_n_vllm_utils["vLLM utils<br/>generation helper<br/>[vllm_utils.py]"]
end

node_n_notebooks -->|"curates"| node_n_dataset_kegg
node_n_notebooks -->|"curates"| node_n_dataset_variant
node_n_dataset_utils -->|"supports"| node_n_dataset_kegg
node_n_dataset_utils -->|"supports"| node_n_dataset_variant
node_n_dna_utils -->|"prepares"| node_n_nucleotide_module
node_n_nucleotide_module -->|"feeds"| node_n_dna_module
node_n_dna_module -->|"backbone"| node_n_dna_only
node_n_dna_module -->|"encodes"| node_n_dna_llm
node_n_dna_module -->|"serves"| node_n_dna_vllm
node_n_dl_processing -->|"formats"| node_n_dl_chat
node_n_dl_processing -->|"adapts inputs"| node_n_dna_llm
node_n_dl_chat -->|"prompts"| node_n_dna_llm
node_n_train_dna_only -->|"trains"| node_n_dna_only
node_n_train_dna_qwen -->|"trains"| node_n_dna_llm
node_n_train_grpo -->|"runs"| node_n_grpo_trainer
node_n_grpo_config -->|"configures"| node_n_grpo_trainer
node_n_grpo_trainer -->|"fine-tunes"| node_n_dna_llm
node_n_reason -->|"uses"| node_n_dna_vllm
node_n_eval -->|"uses"| node_n_vllm_utils
node_n_eval -->|"evaluates"| node_n_dna_vllm
node_n_save_dna -->|"exports"| node_n_train_dna_only
node_n_save_grpo -->|"exports"| node_n_train_grpo

click node_n_dataset_kegg "https://github.com/bowang-lab/bioreason/blob/main/bioreason/dataset/kegg.py"
click node_n_dataset_variant "https://github.com/bowang-lab/bioreason/blob/main/bioreason/dataset/variant_effect.py"
click node_n_dataset_utils "https://github.com/bowang-lab/bioreason/blob/main/bioreason/dataset/utils.py"
click node_n_notebooks "https://github.com/bowang-lab/bioreason/blob/main/data/README.md"
click node_n_dna_module "https://github.com/bowang-lab/bioreason/blob/main/bioreason/dna_modules/dna_module.py"
click node_n_nucleotide_module "https://github.com/bowang-lab/bioreason/blob/main/bioreason/dna_modules/nucleotide_module.py"
click node_n_dna_utils "https://github.com/bowang-lab/bioreason/blob/main/bioreason/utils/dna_utils.py"
click node_n_dna_only "https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dna_only.py"
click node_n_dna_llm "https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dna_llm.py"
click node_n_dna_vllm "https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dna_vllm.py"
click node_n_dl_processing "https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dl/processing_dl.py"
click node_n_dl_chat "https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dl/chat_template_dl.py"
click node_n_grpo_trainer "https://github.com/bowang-lab/bioreason/blob/main/bioreason/trainer/grpo_trainer.py"
click node_n_grpo_config "https://github.com/bowang-lab/bioreason/blob/main/bioreason/trainer/grpo_config.py"
click node_n_reason "https://github.com/bowang-lab/bioreason/blob/main/reason.py"
click node_n_eval "https://github.com/bowang-lab/bioreason/blob/main/eval_kegg_dna_vllm.py"
click node_n_save_dna "https://github.com/bowang-lab/bioreason/blob/main/bioreason/utils/save_ckpt_dna.py"
click node_n_save_grpo "https://github.com/bowang-lab/bioreason/blob/main/bioreason/utils/save_grpo_ckpt.py"
click node_n_vllm_utils "https://github.com/bowang-lab/bioreason/blob/main/bioreason/utils/vllm_utils.py"
click node_n_train_dna_only "https://github.com/bowang-lab/bioreason/blob/main/train_dna_only.py"
click node_n_train_dna_qwen "https://github.com/bowang-lab/bioreason/blob/main/train_dna_qwen.py"
click node_n_train_grpo "https://github.com/bowang-lab/bioreason/blob/main/train_grpo.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_n_dataset_kegg,node_n_dataset_variant,node_n_dataset_utils,node_n_notebooks toneBlue
class node_n_dna_module,node_n_nucleotide_module,node_n_dna_utils toneAmber
class node_n_dna_only,node_n_dna_llm,node_n_dna_vllm,node_n_dl_processing,node_n_dl_chat toneMint
class node_n_grpo_trainer,node_n_grpo_config,node_n_train_dna_only,node_n_train_dna_qwen,node_n_train_grpo toneRose
class node_n_reason,node_n_eval,node_n_save_dna,node_n_save_grpo,node_n_vllm_utils toneIndigo
```

## Components

### Data curation

Offline notebooks and dataset loaders for KEGG and variant-effect benchmarks.

- [KEGG data](https://github.com/bowang-lab/bioreason/blob/main/bioreason/dataset/kegg.py): dataset loader · Loads and prepares KEGG-derived biological reasoning examples. · `bioreason/dataset/kegg.py`
- [Variant effects](https://github.com/bowang-lab/bioreason/blob/main/bioreason/dataset/variant_effect.py): dataset loader · Handles coding and non-SNV variant-effect datasets. · `bioreason/dataset/variant_effect.py`
- [Dataset utils](https://github.com/bowang-lab/bioreason/blob/main/bioreason/dataset/utils.py): shared dataset code · Common dataset logic and preprocessing helpers. · `bioreason/dataset/utils.py`
- [Curation notebooks](https://github.com/bowang-lab/bioreason/blob/main/data/README.md): offline curation · Notebook-based dataset inspection and construction workflows. · `data/README.md`

### DNA pipeline

Sequence normalization, DNA modules, and tokenization utilities.

- [DNA module](https://github.com/bowang-lab/bioreason/blob/main/bioreason/dna_modules/dna_module.py): sequence encoder · Core DNA-side abstraction for model-ready sequence features. · `bioreason/dna_modules/dna_module.py`
- [Nucleotide module](https://github.com/bowang-lab/bioreason/blob/main/bioreason/dna_modules/nucleotide_module.py): sequence frontend · Nucleotide-specific handling and normalization layer. · `bioreason/dna_modules/nucleotide_module.py`
- [DNA utils](https://github.com/bowang-lab/bioreason/blob/main/bioreason/utils/dna_utils.py): sequence utilities · Shared DNA parsing, normalization, and input preparation. · `bioreason/utils/dna_utils.py`

### Modeling

Standalone DNA, multimodal DNA-LLM, and vLLM-oriented model paths.

- [DNA only](https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dna_only.py): baseline model · Standalone DNA foundation model baseline. · `bioreason/models/dna_only.py`
- [DNA-LLM](https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dna_llm.py): multimodal model · Hybrid DNA plus language-model reasoning architecture. · `bioreason/models/dna_llm.py`
- [DNA vLLM](https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dna_vllm.py): inference model · Generation-oriented integration for fast batched inference. · `bioreason/models/dna_vllm.py`
- [DL processing](https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dl/processing_dl.py): prompt adapter · Transforms biological inputs into LLM-ready structured prompts. · `bioreason/models/dl/processing_dl.py`
- [DL chat template](https://github.com/bowang-lab/bioreason/blob/main/bioreason/models/dl/chat_template_dl.py): template adapter · Defines instruction/chat formatting for the multimodal LLM path. · `bioreason/models/dl/chat_template_dl.py`

### Training

Supervised fine-tuning and GRPO reinforcement-learning stack.

- [GRPO trainer](https://github.com/bowang-lab/bioreason/blob/main/bioreason/trainer/grpo_trainer.py): rl loop · Reinforcement-learning training loop for GRPO fine-tuning. · `bioreason/trainer/grpo_trainer.py`
- [GRPO config](https://github.com/bowang-lab/bioreason/blob/main/bioreason/trainer/grpo_config.py): training config · Hyperparameters and runtime settings for GRPO. · `bioreason/trainer/grpo_config.py`
- [Train DNA](https://github.com/bowang-lab/bioreason/blob/main/train_dna_only.py): entrypoint · Standalone DNA model training script. · `train_dna_only.py`
- [Train DNA-Qwen](https://github.com/bowang-lab/bioreason/blob/main/train_dna_qwen.py): entrypoint · DNA plus Qwen-style model training script. · `train_dna_qwen.py`
- [Train GRPO](https://github.com/bowang-lab/bioreason/blob/main/train_grpo.py): entrypoint · Stage for GRPO reinforcement-learning tuning. · `train_grpo.py`

### Inference

Reasoning, evaluation, and checkpoint export workflows.

- [Reason](https://github.com/bowang-lab/bioreason/blob/main/reason.py): inference entrypoint · General reasoning and inference script. · `reason.py`
- [KEGG eval](https://github.com/bowang-lab/bioreason/blob/main/eval_kegg_dna_vllm.py): benchmark eval · Specialized KEGG evaluation with vLLM acceleration. · `eval_kegg_dna_vllm.py`
- [Save DNA ckpt](https://github.com/bowang-lab/bioreason/blob/main/bioreason/utils/save_ckpt_dna.py): checkpoint export · Exports DNA training checkpoints to a normalized format. · `bioreason/utils/save_ckpt_dna.py`
- [Save GRPO ckpt](https://github.com/bowang-lab/bioreason/blob/main/bioreason/utils/save_grpo_ckpt.py): checkpoint export · Exports GRPO checkpoints for downstream use. · `bioreason/utils/save_grpo_ckpt.py`
- [vLLM utils](https://github.com/bowang-lab/bioreason/blob/main/bioreason/utils/vllm_utils.py): generation helper · Shared helpers for vLLM-based generation and evaluation. · `bioreason/utils/vllm_utils.py`

## Connections

- Curation notebooks → KEGG data: curates · Notebook workflows create KEGG benchmark data.
- Curation notebooks → Variant effects: curates · Notebook workflows create variant-effect benchmark data.
- Dataset utils → KEGG data: supports · Shared dataset logic used by KEGG loaders.
- Dataset utils → Variant effects: supports · Shared dataset logic used by variant-effect loaders.
- DNA utils → Nucleotide module: prepares · Utilities normalize sequences for nucleotide processing.
- Nucleotide module → DNA module: feeds · Nucleotide handling feeds the core DNA module.
- DNA module → DNA only: backbone · DNA module powers the standalone DNA baseline.
- DNA module → DNA-LLM: encodes · DNA representations are injected into the multimodal model.
- DNA module → DNA vLLM: serves · DNA features are reused by the inference-oriented path.
- DL processing → DL chat template: formats · Processing layer applies the chat/instruction template.
- DL processing → DNA-LLM: adapts inputs · Bridges biological features into the multimodal model.
- DL chat template → DNA-LLM: prompts · Chat template shapes the language-model side of reasoning.
- Train DNA → DNA only: trains · Entry script trains the DNA-only model.
- Train DNA-Qwen → DNA-LLM: trains · Entry script trains the DNA-LLM stack.
- Train GRPO → GRPO trainer: runs · Training entrypoint launches the GRPO loop.
- GRPO config → GRPO trainer: configures · Config defines GRPO training behavior.
- GRPO trainer → DNA-LLM: fine-tunes · RL training updates the multimodal reasoning model.
- Reason → DNA vLLM: uses · Inference script drives the vLLM-backed model path.
- KEGG eval → vLLM utils: uses · Benchmark evaluation relies on vLLM helpers.
- KEGG eval → DNA vLLM: evaluates · KEGG evaluation runs on the inference model path.
- Save DNA ckpt → Train DNA: exports · Converts DNA training outputs to reusable checkpoints.
- Save GRPO ckpt → Train GRPO: exports · Converts GRPO outputs to reusable checkpoints.
