---

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

🐍 A Python interpreter that remembers	One process per session. Imports, dataframes and fitted models survive from one call to the next, so the agent works in small steps instead of resending a script every time. One left unused for half an hour is retired to reclaim its memory — and the agent is told, rather than discovering it as a NameError.
🧬 21 research-function skills	Biomni's biomedical library, one skill per module, carrying real signatures — parameter types, defaults, and what each one means. Loaded on demand, so 218 functions cost ~1.6k tokens of context instead of ~26k. (Needs Biomni installed.)
🗄️ A data lake skill	The biomedical datasets actually downloaded on this machine, with exact paths, sizes, and licence flags. Prefer local data over a web round trip.
🔧 A software skill	The bioinformatics packages and CLI tools actually installed here — so the agent reaches for samtools instead of reimplementing it.
🔍 An honest environment report	The /biomni command and a Settings page telling you exactly what works, what doesn't, and which package would fix it — with the price, so a 151 MB single-function dependency never reads like a free one.
📤 An outlet for results	run_python returns text, capped — a plot cannot be printed and a real table gets truncated. The interpreter has an output directory bound as BIOMNI_OUT; files written there are named back to the model, and Settings → Biomni shows them: a figure inline, a CSV as a table, anything textual as its head — or downloads the file whole.
🧪 A data lake browser	Settings → Biomni lists all 76 datasets with sizes, marks what is on disk, and fetches one at a time. Non-commercial datasets need an explicit acknowledgement.

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.

Installing from source instead (for development)

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

This packs a tarball with lib/ prebuilt and installs that, so pnpm never needs to run a build script for it.

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.

By hand, or in a container

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

For deployments that would rather provision once than have every user build a venv, the Dockerfile builds the interpreter as an image. It is more moving parts — the plugin's python/ directory has to be mounted in and the python setting has to name a wrapper that runs inside the container — and the file explains the wiring. CI builds the image and runs the probe inside it on every push, so "it builds" is checked rather than claimed.

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:

	exclusive cost	buys
rdkit	151 MB	1 function
cobra	147 MB	2 functions
scholarly	119 MB (drives a real browser)	1 function
statsmodels	68 MB	2 functions

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
  idleTimeoutMs: 1800000                  # retire an unused interpreter after 30 min; 0 = never
  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
/biomni-out          what the work has produced

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.

An idle interpreter costs 298 MB. Measured with the usual stack imported — numpy, pandas, scipy, matplotlib, scikit-learn — against 74 MB for a bare one, held for as long as the session exists. So one left unused for idleTimeoutMs is retired, and the next call tells the agent that its namespace is empty and why. That notice is the point: a namespace that quietly empties itself is the same failure as an unadvertised missing dependency, arrived at from the other direction.

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.