Bio tools

Home page

An interface for running arbitrary CLI applications for biology and chemistry. It focuses on tools with permissive licencing, and ones which are popular. Available as a rust library, a python library, and a standalone CLI application. If you'd like support for a new tool, please create an issue on Github.

Includes the most popular tools for structure prediction, sequence prediction, and drug design. Examples:

• AlphaFold 3
• ProteinMPNN and LigandMPNN
• Boltz-2 / BoltzGen
• RFdiffusion3 and RFantibody
• Chai-1
• Protenix
• BindCraft
• OpenDDE
• ImmuneBuilder
• ThermoMPNN

Around 35 more are covered; see Tool::ALL and tool_definitions::catalog for the full set, each with its own summary, license, and official links.

Handles the following tasks:

• Install
• Uninstall
• Run (Including abstractions over what inputs are accepted per tool, e.g. for the purposes of building a UI)
• Check status/health
• View metadata

Many of these tools only work on Linux. If you attempt to install one of these on Windows, you will get an error explicitly stating this. The list commands states which tools are Linux only, if you are on a different OS.

Quickstart

pip install bio_tools_app --break-system-packages


bio_tools install boltz2

bio_tools run open_dde --version


bio_tools list-quick

Note: Does not break system packages; this just downloads a binary and adds it to the path. That override is required only on certain Linux distributions.

As a CLI application

pip install bio_tools_app (See note above about --break-system-packages if you get an error when running this)

This installs the prebuilt bio_tools executable onto your PATH. uv tool install bio_tools_app works too.

Alternatively, download a prebuilt binary from the Releases page, or build it with Cargo:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

cargo install bio_tools

Any of these leaves you with bio_tools on your path.

As a Python library

uv add athanor_bio_tools Or pip install athanor_bio_tools

The PyPI distribution is named athanor_bio_tools. The module you import is bio_tools.

As a Rust library

cargo add bio_tools

CLI application usage

Run the program with no parameters to see its functionality: bio_tools

Usage:

  bio_tools [--root <directory>] install <tool>
  bio_tools [--root <directory>] uninstall <tool>
  bio_tools [--root <directory>] status-quick <tool>
  bio_tools [--root <directory>] status or status-full <tool>
  bio_tools [--root <directory>] run <tool> [-- <tool arguments...>]

  bio_tools [--root <directory>] list-quick

  bio_tools [--root <directory>] list or list-full

  bio_tools metadata <tool>

Examples:

• bio_tools install boltz2
• bio_tools uninstall proteinmpnn
• bio_tools list-quick

Generic interfaces and code consolidation

This library provides an interface for input and output. This abstracts over the differences between tools, so applications can add many of them without repeating code. This library was built as the backbone of the Athanor Bio Tools web UI, and the integrations in Molchanica. These use the Python and Rust libraries respectively. Bio Tools is designed to reduce repetition between these projects.

The CLI application is intended for cases where you're not writing software, but want to install these tools directly, without handling the system dependencies and python environments for each tool.

Installing tools

(todo: Clean up these sections which describe implementation and code samples. And create an example folder with excerpts from Bio Web and Molchanica.)

Details depend on the tool; most work by downloading and placing application executables in the appropriate places. Many of these use Python; it sets them up using uv, Micromamba, or MiniConda in isolated environments. Micromamba is a faster, less-encumbered version of Conda which works for some, but not all Conda packages.

InstallLayout::process_executables standardizes both consumers on assets under process_executables/ and environments under process_executables/python_envs/. InstallLayout::split remains available for custom roots. A progress callback can be attached with Installer::with_reporter for a GUI or structured setup log.

Rust:

use bio_tools::{install::Installer, tool_definitions::Tool};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut installer = Installer::for_process_executables("process_executables")?;
    installer.install(Tool::OpenDde)?;

    // Independent recipes continue after an upstream failure.
    let report = installer.install_many([Tool::Boltz2, Tool::ProteinMpnn]);
    for failure in &report.failed {
        eprintln!("{}: {}", failure.tool.name(), failure.error);
    }

    // Status: `status_quick` inspects markers, executables, and required assets
    // without launching the tool; `status_full` also runs its help/version probe.
    let status = installer.status_quick(Tool::OpenDde);
    println!("{:?}: {}", status.result, status.detail);

    let report = installer.uninstall(Tool::OpenDde)?;
    println!("Removed {} paths", report.removed.len());
    Ok(())
}

Python (equivalent):

from pathlib import Path
import bio_tools

root = Path("process_executables")
installer = bio_tools.Installer(root)
installer.install(bio_tools.Tool("opendde"))

# Independent recipes continue after an upstream failure.
for slug in ("boltz2", "proteinmpnn"):
    try:
        installer.install(bio_tools.Tool(slug))
    except RuntimeError as error:
        print(f"{slug}: {error}")

status = installer.status_quick(bio_tools.Tool("opendde"))
print(status.result, status.detail)

report = installer.uninstall(bio_tools.Tool("opendde"))
print(f"Removed {len(report.removed)} paths")

Running tools

run::CommandSpec describes a shell-free invocation independently of any one tool. CommandRunner builds a std::process::Command, overlays environment variables, writes optional stdin (or closes it when absent), drains bounded stdout and stderr concurrently, enforces a timeout, and either returns or rejects non-zero exits according to ExitPolicy.

Rust:

use std::time::Duration;

use bio_tools::run::{CommandSpec, RunLogSpec, run};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let command = CommandSpec::new("opendde")
        .args(["predict", "input.yaml"])
        .current_dir("work")
        .timeout(Duration::from_secs(600))
        .run_log(RunLogSpec::new("process_executables/run_logs", "opendde").artifact("."));

    let output = run(&command)?;
    println!("{}", output.stdout_lossy());
    Ok(())
}

Python (equivalent):

from pathlib import Path
import bio_tools

result = bio_tools.CommandSpec(
    ["opendde", "predict", "input.yaml"],
    cwd=Path("work"),
    timeout=600,
    run_log_dir=Path("process_executables/run_logs"),
    run_name="opendde",
).run()

print(result.stdout)
print(result.run_log_dir)

Installer::tool_command (Python: Installer.run) is the variant to reach for when the tool lives in a managed environment rather than on PATH; it resolves the installed console entry point for you.

RFdiffusion3 and ProteinMPNN examples and their input files are bundled with the library. Rust callers use tool_definitions::presets::payload(slug, preset_id, &overrides) to load the shared form values, and presets::materialize(slug, &values, job_directory) to replace bundled file references with absolute paths. This includes references inside RFD3's JSON inputs, and ProteinMPNN's FASTA and PSSM inputs, without a download or a Bio Web dependency.

Python callers can do both in one call:

from pathlib import Path
import bio_tools

values = bio_tools.catalog_preset(
    "rfd3", "demo/M0255_1mg5_unfixed",
    overrides={"n_batches": 1},
    workdir=Path("work"),
)
print(values["input"])  # An existing PDB in the job directory.

These are editable field values, which the caller maps to the tool's native inputs and command arguments. Omit workdir to keep portable bio-tools:// references for a form or saved job. presets::input_text (Python: catalog_input_text) resolves a reference to its contents for consumers accepting file text. Explicit overrides, including empty values, take precedence; materialization leaves existing files intact. Keep the job directory until inference has finished.

Run logs

When a run log is configured, each invocation is assigned a unique directory below the given root and run name. run.log combines the exact argument vector, optional stdin, result, and complete stdout/stderr. The same streams are also available as stdout.txt and stderr.txt; inputs/ contains the pre-run artifact snapshot and outputs/ contains only files created or changed by the command.

In general, these logs hold the full information used to invoke the tool, and its output. This includes stdout, stderr, params and input files it was run with, and its entire output including stdout, stderr, and output files (e.g. mmCIF).

Standalone CLI

The bio_tools executable wraps the same installer, status, and command-runner APIs for shell use:

bio_tools install opendde

bio_tools status-quick opendde

bio_tools status opendde

bio_tools metadata opendde

bio_tools run opendde -- --help


bio_tools list-quick

bio_tools list


bio_tools dir


bio_tools uninstall opendde

dir prints the directory tools are installed to, along with the sub-directories holding tool assets and Python environments, and which of the settings below chose it. It creates nothing.

status-quick inspects installation markers, executables, and required assets without launching the tool. status or status-full (They do the same) also runs the tool's help/version probe and imports Torch or JAX where applicable to report its compute device. The corresponding list commands are list-quick and list or list-full. run resolves an installed console entry point inside that managed environment, so it does not require the tool on PATH. Tools that only expose a Python module or checkout script still need a tool-specific library invocation.

Tool installation directory

The CLI installs into one per-user directory, so the same tools are found no matter which directory bio_tools is launched from. Environments and model weights can reach tens of gigabytes, so it is the platform's per-user data directory rather than a configuration or roaming one:

Inside it, tools/ holds source checkouts, binary distributions, and model data, and each tool's isolated Python environment is a sibling directory named <tool>-venv.

Two settings override that default, highest precedence first:

• --root <directory>, for one invocation
• $BIO_TOOLS_ROOT, for every invocation in that environment

Run bio_tools dir to print the directory in effect and which of the three chose it. The library API takes its root as an argument and has no default; bio_tools::install::default_root() returns the same canonical directory for callers that want it.

Example uses

• Building a GUI (Web or native application) to these tools
• Setting up an API to programmatically interface.

Python bindings

The python/ package builds an ABI3 wheel with PyO3 and maturin, published to PyPI as athanor_bio_tools. It exposes the same process metadata, command runner, installer, and status probes; see the examples above, and the Rust docs for details on the underlying types.

The python_cli/ package is unrelated to those bindings: it wraps the compiled bio_tools executable in a wheel, published to PyPI as bio_tools_app, so the CLI can be installed with pip. This makes it easy to install and add to PATH for python users.

Compiling from source

Run this from the project root. You only need the first line if you don't have the Rust toolchain installed. (And that specific command is for Linux; MacOS and Windows have similarly straightforward ways to install it)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

cargo b --release

The binary will be placed in target/release

A flippant response to "Why would I want this?"

Rosetta's Protein Design workshop dedicates a full day to installing these; this lib/application trivializes it.