README.md

---
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
base_model: Qwen/Qwen3-4B-Base
tags:
  - biology
  - biomedical
  - perturbation-response
  - reinforcement-learning
  - qwen3
  - transformers
  - vllm
---

# PertMind

PertMind is a biological language model built around a central discovery: public cellular perturbation atlases can be reorganized into reinforcement-learning environments, where measured gene responses act as computable reward signals for biological reasoning. Instead of relying only on manually curated reasoning traces, PertMind combines trusted-trajectory supervised initialization with perturbation-derived reinforcement learning for perturbation-centered inference and biological profile generation.

PertMind is initialized from [Qwen/Qwen3-4B-Base](https://huggingface.co/Qwen/Qwen3-4B-Base). The project repository is [shapsider/PertMind](https://github.com/shapsider/PertMind).

![Figure 1](assets/Figure1.png)

*Figure 1. Schematic scope of the capabilities enabled by PertMind. Reasoning-based applications use natural-language inference for perturbation-response prediction, perturbation prioritization, mechanism reasoning, and proposal planning. Embedding-based applications encode PertMind-generated biological profiles into reusable molecular, cellular, and donor representations for reference mapping, cellular perturbation-response prediction, and donor-level tumor-state reference mapping. The figure summarizes the intended capability space, not benchmark performance. Within this space, the quantitatively evaluated subset in the manuscript covers forward perturbation-response prediction, reverse perturbation-condition inference, phenotypic-screen hit prioritization, biological-process naming, and molecular-, cellular-, and donor-level reference mapping.*

## Model Summary

PertMind starts from the Qwen3-4B base model family and treats perturbation-response prediction as a training interface for biological reasoning. Each query is centered on a `(cell line, perturbation, target gene)` triplet. The model receives retrieved biological context, but the query-specific endpoint remains hidden from the prompt. Training then rewards responses that align with experimentally observed perturbation outcomes.

The released package preserves the model configuration, tokenizer assets, and three runnable inference entry points included in this repository:

- `inference_vllm.py`
- `inference_transformers.py`
- `tui_chat.py`

## Perturbation-Derived RL

PertMind operationalizes perturbation-derived reinforcement learning in three stages:

1. Gene-centered queries are assembled from the Tahoe-100M perturbation atlas and paired with experimentally derived `Up`, `Down`, or `No` response labels.
2. A small trusted set of model-generated trajectories provides structured supervised initialization, giving the policy an evidence-grounded starting point before reinforcement learning.
3. Group Relative Policy Optimization then optimizes a composite reward with three parts: a gene-level endpoint reward, a pathway-direction reward derived from transcriptional response summaries, and a format reward that keeps outputs parseable.

This setup is meant to test whether reinforcement on experimental endpoints can concentrate reusable biological strategies that are already accessible to a pretrained language model.

## Operational Emergence

In the PertMind manuscript, *emergence* is used in an operational sense: a capability appears on a target task that was absent from post-training. PertMind is post-trained only on forward perturbation-response prediction, while the manuscript evaluates transfer to other biological tasks such as reverse perturbation-condition inference, phenotypic-screen prioritization, biological-process interpretation, and multiscale representation construction.

This framing is intentionally bounded. Transfer outside the post-training objective supports the hypothesis that PertMind learns reusable biological strategies, but it does not prove that every free-text reasoning trace is mechanistically faithful.

## Intended Uses

Evidence-supported uses described in the manuscript include:

- forward perturbation-response reasoning in held-out biological contexts;
- reverse perturbation-condition inference and related transfer settings absent from post-training;
- biological-process interpretation and screen-oriented biological briefing;
- generation of PertMind-derived biological profiles for downstream molecular, cellular, and donor-level representations.

Broader intended capability scope illustrated in Figure 1 includes mechanism reasoning and proposal planning. Figure 1 should be read as a capability overview, not as a benchmark summary.

## Out-Of-Scope Uses

PertMind is not intended for:

- clinical diagnosis, treatment selection, or other medical decision-making;
- replacing wet-lab validation or expert biological review;
- claims of faithful causal mechanism recovery from endpoint accuracy alone;
- unrestricted deployment to perturbation modalities, tissues, doses, or disease states that were not studied in the released work.

## Quick Start

Create a clean environment and install dependencies:

```bash
conda create -n pertmind python=3.11 -y
conda activate pertmind
pip install -r requirements.txt
```

If multiple Python environments are present, verify that the active interpreter is the one from `pertmind`:

```bash
which python
python -c "import sys; print(sys.executable)"
```

Run a single prompt with vLLM:

```bash
python inference_vllm.py \
  --model . \
  --prompt "In HCT116, predict how LMBR1 changes expression of SLC26A6."
```

Run a single prompt with Transformers:

```bash
python inference_transformers.py \
  --model . \
  --prompt "In HCT116, predict how LMBR1 changes expression of SLC26A6."
```

Start the terminal chat interface:

```bash
python tui_chat.py --model . --backend vllm
```

Useful TUI commands:

```text
/reset  clear conversation history
/exit   quit
```

## Tested Setup

The release content was prepared against the included runtime files and dependency pins:

- Python 3.11
- PyTorch 2.10.0
- Transformers 5.14.0
- Accelerate 1.14.0
- Safetensors 0.8.0
- vLLM 0.19.1

The model package is approximately 7.5 GB in `bfloat16`. A GPU with at least 16 GB VRAM is recommended for basic inference. Larger context lengths and vLLM serving may require more VRAM, and the first vLLM run may spend extra time compiling and caching CUDA graphs.

## Limitations And Responsible Use

- Endpoint correctness does not by itself establish a faithful causal mechanism.
- Free-text trajectories are auditable, but the reward does not verify every intermediate reasoning step.
- Pathway supervision is a transcriptional proxy and does not directly measure protein activity, metabolic flux, spatial signaling, or causal pathway activation.
- The evaluated datasets, interventions, and downstream tasks cover only part of biological diversity, so generalization outside the studied settings remains unresolved.
- Retrieval resources and trusted trajectories may propagate omissions, annotation errors, and historical biases from their sources.
- PertMind-derived embeddings still depend on task-specific projections, aggregation, and downstream supervision.

PertMind is released for research use, hypothesis generation, and method development.

## License

This repository is released under the [Apache-2.0 License](LICENSE).