Biomanus/README.md

# HypoBioOS

Step-by-step guide for setting up Biomni and running the generic paper reproduction workflow in this repository.

This repository is developed based on the open-source Biomni codebase from [snap-stanford/biomni](https://github.com/snap-stanford/biomni). We extend the original Biomni agent framework with MCP server generation, graph-guided tool retrieval, dynamic MCP routing, and benchmark-oriented experiment runners.

## 1. Goal

This document explains how to:

- set up the Biomni runtime environment,
- configure the LLM endpoint used by the reproduction script,
- verify MCP servers are discoverable,
- run the generic reproduction runner,
- reproduce the built-in FOXJ1 example,
- run the same workflow on a different paper.

The main script covered here is:

```text
/225040511/project/Biomni/reproduce_foxj1_paper.py
```

Although the filename still contains `foxj1`, the script is now a generic runner.

## 2. Prerequisites

Before you start, make sure you have:

- access to this Biomni repository,
- Conda installed,
- a working Python environment compatible with Biomni,
- an API key for a model endpoint,
- generated MCP server directories under `biomni_web/backend/data/mcp_generated/`.

## 3. Enter The Repository

```bash
cd /225040511/project/Biomni
```

## 4. Build The Biomni Environment

Follow the environment setup instructions in:

```text
biomni_env/README.md
```

After the environment is created, activate it:

```bash
conda activate biomni_e1
```

If you are running Biomni from source, install the current repository into the environment:

```bash
pip install -e .
```

If you prefer the upstream GitHub version instead:

```bash
pip install git+https://github.com/snap-stanford/Biomni.git@main
```

## 5. Configure The Model Endpoint

The current `reproduce_foxj1_paper.py` script creates the agent with:

```python
source="Custom"
```

This means the script is using an OpenAI-compatible HTTP endpoint through Biomni's custom backend path.

The current code reads credentials in this order:

1. `DEEPSEEK_API_KEY`
2. `OPENAI_API_KEY`
3. fallback to `"EMPTY"`

The current code also reads:

- `DEEPSEEK_BASE_URL`
- `DEEPSEEK_MODEL_NAME`

So if you want to use OpenAI, you should not only set `OPENAI_API_KEY`, but also point `DEEPSEEK_BASE_URL` to the OpenAI API endpoint and set `DEEPSEEK_MODEL_NAME` to an OpenAI model name.

### Option A. Use DeepSeek

Set these environment variables:

```bash
export DEEPSEEK_API_KEY="your_api_key"
export DEEPSEEK_BASE_URL="https://api.deepseek.com/v1"
export DEEPSEEK_MODEL_NAME="deepseek-chat"
```

### Option B. Use OpenAI API Key

Use the OpenAI key as the authentication source, but still set the endpoint and model through the same runtime variables used by the script:

```bash
export OPENAI_API_KEY="your_openai_api_key"
export DEEPSEEK_BASE_URL="https://api.openai.com/v1"
export DEEPSEEK_MODEL_NAME="gpt-4.1-mini"
```

You can replace `gpt-4.1-mini` with another OpenAI model that your account can access, for example:

```bash
export DEEPSEEK_MODEL_NAME="gpt-4.1"
```

### Option C. Use Another OpenAI-Compatible Endpoint

If you use another OpenAI-compatible endpoint, point the same variables to your own service:

```bash
export OPENAI_API_KEY="your_custom_endpoint_key"
export DEEPSEEK_BASE_URL="http://your-endpoint/v1"
export DEEPSEEK_MODEL_NAME="your-model-name"
```

### Quick Check

After exporting the variables, you can confirm they are set:

```bash
echo "$DEEPSEEK_BASE_URL"
echo "$DEEPSEEK_MODEL_NAME"
```

If you are using OpenAI:

```bash
echo "$OPENAI_API_KEY"
```

You do not need to print the full key in shared logs. It is enough to verify that the variable is non-empty.

Optional but recommended:

```bash
export BIOMNI_MCP_PYTHON="$(which python)"
```

This ensures the generated MCP config uses the Python interpreter from your active Biomni environment.

## 6. Verify MCP Servers Exist

The script discovers MCP servers from:

```text
biomni_web/backend/data/mcp_generated/
```

Each server is expected to look like:

```text
mcp_<server_name>/app/*_shim_server.py
```

or:

```text
mcp_<server_name>/app/*_server.py
```

You can inspect what the script currently finds:

```bash
python reproduce_foxj1_paper.py --list-servers
```

If the list is empty or missing expected servers, check whether the corresponding generated directories exist under:

```text
/225040511/project/Biomni/biomni_web/backend/data/mcp_generated/
```

## 7. Understand What The Script Does

The script performs these high-level steps:

1. parses your paper title, context, query, input files, and requested MCP servers,
2. discovers available MCP server directories,
3. builds an MCP config YAML file for the selected servers,
4. creates a run directory under `paper_reproduction_runs/`,
5. writes prompt, query, and plan files,
6. initializes `A1`,
7. loads the MCP config,
8. asks Biomni to plan the reproduction steps from your query,
9. lets Biomni select suitable MCP tools during execution,
10. saves logs, final answer, and report files.

## 8. Do A Dry Run First

Before running the full workflow, do a preparation-only run:

```bash
python reproduce_foxj1_paper.py \
  --dataset-profile foxj1 \
  --prepare-only
```

This does not call the model. It only prepares:

- the run directory,
- the MCP config,
- the query file,
- the prompt file,
- the execution plan file.

The output will be written under:

```text
paper_reproduction_runs/
```

## 9. Run The Built-In FOXJ1 Example

Use the built-in dataset profile if you want to reproduce the FOXJ1 example workflow.

Command:

```bash
python reproduce_foxj1_paper.py \
  --dataset-profile foxj1 \
  --query "Firstly, whether FOXJ1 and GMNC were up-regulated in LuCaP35CR, then whether ABCB1 was up-regulated in LuCaP70CR, and finally the enrichment analysis of pathways related to cilia/microtubules was performed"
```

What this does:

1. loads the built-in FOXJ1 profile,
2. downloads the associated GEO processed files if needed,
3. selects the preferred MCP server set for that profile,
4. builds the execution prompt from your natural-language query,
5. runs Biomni with MCP enabled,
6. writes logs and outputs into the run directory.

## 10. Run A Different Paper

If you want to run another paper, provide your own paper metadata and inputs.

Minimal example:

```bash
python reproduce_foxj1_paper.py \
  --paper-title "Your Paper Title" \
  --context-file /path/to/paper_summary.md \
  --input-file /path/to/data1.csv \
  --input-file /path/to/data2.tsv \
  --query "Reproduce the main findings, choose suitable MCP tools, run the feasible analyses, and summarize what is supported by the provided data." \
  --server jq \
  --server bioconductor-clusterprofiler \
  --server gseapy
```

You can also pass entire directories:

```bash
python reproduce_foxj1_paper.py \
  --paper-title "Another Paper" \
  --paper-context "Short summary of the paper and the results you want to reproduce." \
  --input-dir /path/to/input_folder \
  --query "Check differential patterns and enrichment results." \
  --server all
```

## 11. Important Command Options

Common options supported by the script:

- `--paper-title`: title of the paper for this run.
- `--paper-context`: short context text passed directly on the command line.
- `--context-file`: markdown or text file containing paper context.
- `--query`: natural-language reproduction request.
- `--input-file`: input file to include, can be used multiple times.
- `--input-dir`: input directory to include, can be used multiple times.
- `--dataset-profile foxj1`: use the built-in FOXJ1 example profile.
- `--server`: choose MCP servers explicitly.
- `--server all`: register all discovered MCP servers.
- `--prepare-only`: generate files without running the model.
- `--list-servers`: print discovered MCP servers and exit.

## 12. What Files You Should Expect

For each run, the script creates a folder like:

```text
paper_reproduction_runs/<run_name>/
```

Inside it, you should see files such as:

```text
mcp_config.yaml
paper_context.md
reproduction_query.txt
execution_plan.md
reproduction_prompt.txt
results/biomni_execution_log_*.txt
results/biomni_execution_log_*.json
results/biomni_final_answer_*.txt
results/biomni_run_metadata_*.json
results/biomni_conversation_*.md
results/reproduction_report.md
```

## 13. Recommended First-Time Workflow

If this is your first time running the script, use this exact order:

1. `cd /225040511/project/Biomni`
2. `conda activate biomni_e1`
3. `pip install -e .`
4. export `DEEPSEEK_API_KEY`
5. export `DEEPSEEK_BASE_URL`
6. export `DEEPSEEK_MODEL_NAME`
7. optionally export `BIOMNI_MCP_PYTHON="$(which python)"`
8. run `python reproduce_foxj1_paper.py --list-servers`
9. run `python reproduce_foxj1_paper.py --dataset-profile foxj1 --prepare-only`
10. run the full FOXJ1 example command

## 14. Troubleshooting

If the script does not run, check these items one by one.

### Environment Problems

- Make sure the Conda environment is activated.
- Make sure `pip install -e .` completed successfully.
- Make sure the same Python is used by both Biomni and MCP config generation.

### Model Problems

- Make sure `DEEPSEEK_API_KEY` is set.
- Make sure `DEEPSEEK_BASE_URL` points to a reachable OpenAI-compatible endpoint.
- Make sure `DEEPSEEK_MODEL_NAME` matches a model served by that endpoint.

### MCP Problems

- Run `python reproduce_foxj1_paper.py --list-servers`.
- Confirm the required `mcp_<name>` directories exist.
- Confirm each selected MCP server has an `app/` directory with a `*_shim_server.py` or `*_server.py` file.

### Input Problems

- Confirm all `--input-file` paths exist.
- Confirm all `--input-dir` paths exist.
- If using the `foxj1` profile, let the script finish downloading the GEO processed files.

### Dry Run Problems

- If a full run fails, first retry with `--prepare-only`.
- Check whether the prompt and MCP config are generated correctly before debugging model execution.

## 15. One-Line Reference Commands

List MCP servers:

```bash
python reproduce_foxj1_paper.py --list-servers
```

Prepare only:

```bash
python reproduce_foxj1_paper.py --dataset-profile foxj1 --prepare-only
```

Run FOXJ1:

```bash
python reproduce_foxj1_paper.py --dataset-profile foxj1 --query "Firstly, whether FOXJ1 and GMNC were up-regulated in LuCaP35CR, then whether ABCB1 was up-regulated in LuCaP70CR, and finally the enrichment analysis of pathways related to cilia/microtubules was performed"
```

## 16. Acknowledgements

This work builds on the open-source Biomni project by the Stanford SNAP group: [snap-stanford/biomni](https://github.com/snap-stanford/biomni). We gratefully acknowledge the Biomni authors and contributors for releasing their codebase and biomedical agent framework, which provided the foundation for this development.