The failure this prevents

Give an agent a biomedical tool library and it fails in a particular, nasty way.

It calls query_pubmed. The function exists, but its dependency was never installed, so it raises. The agent does not report the gap — it quietly writes its own PubMed client and hands you the result as though it came from the validated tool. Point it at a data lake it does not have and the same thing happens with a file path: a plausible guess, then a plausible answer.

dsh-biomni's one rule: never advertise what this machine cannot deliver. Everything your agent is told about — every function, dataset, and command-line tool — is generated by checking your actual environment first. Anything missing is either left out, or named out loud along with what it needs.

What your agent gets

It is an ordinary out-of-tree plugin. It does not fork or patch the harness.

Install

1. Add the plugin

dsh plugin --profile web add dsh-biomni

That is the whole step. The CLI reads this package's dsh.bundle.patch declaration and appends dsh-biomni to your profile's bundles — no profile file to edit.

git clone https://github.com/ZhuYanTech/dsh-biomni && cd dsh-biomni
bash scripts/install.sh web

2. Build a Python environment with Biomni

Optional, and worth knowing why. The data lake and software catalogs work immediately — they read a manifest shipped with the plugin, checked against your machine. Only the 21 tool-module skills need Biomni itself, because those are real Python that has to import.

git clone https://github.com/ZhuYanTech/dsh-biomni && cd dsh-biomni
bash scripts/setup-env.sh

The script picks uv when you have it — 11 seconds against minutes for pip, on an identical resolution — and falls back to pip otherwise. It then runs the probe and refuses to claim success unless Biomni actually imports, which is the part that matters: an environment built on Python 3.9, or one where a wheel failed quietly, looks exactly like a working one until the first tool call. It finishes by printing the setting to paste, with the path filled in.

Add --extras for the four opt-in packages below. Pass a directory to build somewhere other than .venv.

curl -sLO https://raw.githubusercontent.com/ZhuYanTech/dsh-biomni/main/python/requirements-biomni.lock.txt
python3.11 -m venv .venv          # 3.11+ required; macOS ships 3.9
.venv/bin/pip install -r requirements-biomni.lock.txt

Measured: 77 packages, 806 MB, 279 of Biomni's 312 functions callable.

Biomni declares three dependencies and needs far more, so requirements-biomni.txt is the real list, reverse-engineered from its source and annotated with what each package unlocks. The .lock.txt beside it pins every transitive version, so two people installing a week apart get the same interpreter.

Four packages sit outside that core tier, in requirements-biomni-extras.txt, because each was measured to cost far more than it unlocks:

Together that is 494 MB for 7 more functions. Install them if you need those seven; nothing else changes. The probe names them with their price rather than suggesting them as if they were free.

3. Point the plugin at that interpreter

Start dsh --profile web, open Settings → Biomni, and set the Python interpreter to /abs/path/to/.venv/bin/python. It takes effect immediately.

Or write it into $DSH_HOME/settings.yaml:

biomni:
  python: /abs/path/to/.venv/bin/python   # the venv from step 2
  dataPath: /abs/path/to/data             # optional: holds biomni_data/
  timeoutMs: 600000
  guardShellPython: true

4. See what you actually got

/biomni              what this interpreter can run, and what would fix the gaps
/biomni-datasets     what data is here, what is available, and what each costs

Modules that import, functions that are callable, datasets on disk, tools installed — and for everything missing, the package that would fix it. Same numbers as the Settings page, because both read the same analysis.

Optional: the biomedical persona

The plugin gives every agent the interpreter and the skills. If you want one agent framed as a biomedical researcher — told to load the workflow skill first, to report missing packages rather than work around them — install the bundled preset:

pnpm run install:preset

Good to know

"Importable" and "callable" are different numbers. A Biomni module can import perfectly and still have functions that raise on call, because some import their dependencies inside the function body. dsh-biomni reports these separately and never averages them into one score — the whole point is that a single "82% available" figure would hide exactly the gap that causes invented results.

The data lake is fetched one dataset at a time. All 76 come to 15.1 GB, and they range from a 4 KB assay table to a 6.2 GB binding database — so almost nobody wants the set. /biomni-datasets lists what is on disk, what is available, and what each one costs; python/fetch.py fetches by name. Nothing downloaded simply means no data-lake skill: a definite answer, not a failure.

Some datasets are non-commercial. Biomni ships a commercial-use subset (41 of 76). A dataset can be downloaded, readable, and still restricted, so the licence is tracked as its own fact, named in the skill, and enforced at the one point where it binds: fetching a restricted dataset needs an explicit acknowledgement.

Python belongs to run_python, not the shell. A guard stops the agent from reaching a different interpreter through bash — but it lets through calls that name your configured interpreter by absolute path, since those reach the right libraries. CLI tools like samtools run through bash as normal; only python and pip are restricted.

Under the hood

Biomni solves the "200+ tool schemas don't fit in context" problem with ToolRetriever, an embedding-based retriever. DSH's skill system already is that, in a better shape: the session catalog carries only a name and one-line description per skill, and the model loads a full body on demand through the skill tool. No embeddings, no similarity search, no retriever that can pick wrong — the selection is the model's own judgement.

Contributors and agents working in this repo should read AGENTS.md, which carries the constraints that are easy to break and hard to notice.

License

MIT. Biomni is MIT-licensed too; individual datasets in its data lake carry their own terms.