How bowang-lab/bioreason works
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: dna_llm.py DNA-LLM · dna_module.py DNA module · grpo_trainer.py GRPO trainer · dna_vllm.py DNA vLLM
Components 22
Data curation
Offline notebooks and dataset loaders for KEGG and variant-effect benchmarks.
- KEGG data · Loads and prepares KEGG-derived biological reasoning examples.
bioreason/dataset/kegg.py - Variant effects · Handles coding and non-SNV variant-effect datasets.
bioreason/dataset/variant_effect.py - Dataset utils · Common dataset logic and preprocessing helpers.
bioreason/dataset/utils.py - Curation notebooks · Notebook-based dataset inspection and construction workflows.
data/README.md
DNA pipeline
Sequence normalization, DNA modules, and tokenization utilities.
- DNA module · Core DNA-side abstraction for model-ready sequence features.
bioreason/dna_modules/dna_module.py - Nucleotide module · Nucleotide-specific handling and normalization layer.
bioreason/dna_modules/nucleotide_module.py - DNA utils · 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 · Standalone DNA foundation model baseline.
bioreason/models/dna_only.py - DNA-LLM · Hybrid DNA plus language-model reasoning architecture.
bioreason/models/dna_llm.py - DNA vLLM · Generation-oriented integration for fast batched inference.
bioreason/models/dna_vllm.py - DL processing · Transforms biological inputs into LLM-ready structured prompts.
bioreason/models/dl/processing_dl.py - DL chat template · 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 · Reinforcement-learning training loop for GRPO fine-tuning.
bioreason/trainer/grpo_trainer.py - GRPO config · Hyperparameters and runtime settings for GRPO.
bioreason/trainer/grpo_config.py - Train DNA · Standalone DNA model training script.
train_dna_only.py - Train DNA-Qwen · DNA plus Qwen-style model training script.
train_dna_qwen.py - Train GRPO · Stage for GRPO reinforcement-learning tuning.
train_grpo.py
Inference
Reasoning, evaluation, and checkpoint export workflows.
- Reason · General reasoning and inference script.
reason.py - KEGG eval · Specialized KEGG evaluation with vLLM acceleration.
eval_kegg_dna_vllm.py - Save DNA ckpt · Exports DNA training checkpoints to a normalized format.
bioreason/utils/save_ckpt_dna.py - Save GRPO ckpt · Exports GRPO checkpoints for downstream use.
bioreason/utils/save_grpo_ckpt.py - vLLM utils · Shared helpers for vLLM-based generation and evaluation.
bioreason/utils/vllm_utils.py
Connections 22
- 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.