Biomni--Im/README.md

Biomni--

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

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:

/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

cd /225040511/project/Biomni

4. Build The Biomni Environment

Follow the environment setup instructions in:

biomni_env/README.md

After the environment is created, activate it:

conda activate biomni_e1

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

pip install -e .

If you prefer the upstream GitHub version instead:

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:

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:

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:

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:

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:

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:

echo "$DEEPSEEK_BASE_URL"
echo "$DEEPSEEK_MODEL_NAME"

If you are using OpenAI:

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:

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:

biomni_web/backend/data/mcp_generated/

Each server is expected to look like:

mcp_<server_name>/app/*_shim_server.py

or:

mcp_<server_name>/app/*_server.py

You can inspect what the script currently finds:

python reproduce_foxj1_paper.py --list-servers

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

/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:

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:

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:

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:

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:

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:

paper_reproduction_runs/<run_name>/

Inside it, you should see files such as:

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:

python reproduce_foxj1_paper.py --list-servers

Prepare only:

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

Run FOXJ1:

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"