dsh-biomni

Readme

<div align="center">

# dsh-biomni

**Biomedical research, wired into [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).**

A persistent Python interpreter, [Biomni](https://github.com/snap-stanford/Biomni)'s 218 research functions,
its 76-dataset data lake, and 113 bioinformatics tools — offered to your agent as skills
that only ever promise what your machine can actually deliver.

[![DSH Plugin](https://img.shields.io/badge/DSH-plugin-5b6cff)](https://github.com/topics/dsh-plugin)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

**English** · [简体中文](./README.zh-CN.md) · [Changelog](./CHANGELOG.md)

</div>

---

## 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

```sh
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.

<details>
<summary>Installing from source instead (for development)</summary>

```sh
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.

</details>

### 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.

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

The script picks [uv](https://docs.astral.sh/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`.

<details>
<summary>By hand, or in a container</summary>

```sh
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.

</details>

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

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

```sh
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](./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.