External Tool Runtimes¶
Liquid Agent can now manage a dedicated external-tool layer for liquid-biopsy methods that are not part of the main Python kernel. This layer is intentionally separate from the default environment: Python packages with strict pins, R/Bioconductor packages, Snakemake workflows, source-only research code, and system binaries are installed or checked in isolated runtimes where possible.
Use this page when a method is not just a recommendation and you want to know whether Liquid Agent can actually call its runtime.
CLI¶
Show all registered external runtimes:
liquid-agent tools status
Show one runtime as JSON:
liquid-agent tools status --tool purecn --json
One-command setup for common stable runtimes:
liquid-agent tools bootstrap
liquid-agent tools bootstrap --execute
Prepare every auto-installable runtime:
liquid-agent tools bootstrap --profile all
liquid-agent tools bootstrap --profile all --execute
Dry-run an installer:
liquid-agent tools install purecn
Execute the installer:
liquid-agent tools install purecn --execute
Run a smoke test:
liquid-agent tools smoke purecn
Run a command through the wrapper:
liquid-agent tools run cnvkit -- cnvkit.py --help
liquid-agent tools run purecn -- Rscript -e "library(PureCN); packageVersion('PureCN')"
liquid-agent tools run dorado_modkit -- modkit --version
Write a status report:
liquid-agent tools status --output-dir <output_dir>
This writes:
liquid_biopsy_external_tool_status.jsonliquid_biopsy_external_tool_status.md
Status Meaning¶
| Field | Meaning |
|---|---|
installed |
The runtime, source checkout, executable, Python module, or R package is locally callable through Liquid Agent. |
ready |
The runtime is installed and all data-specific resources are configured, including model checkpoints, reference panels, manifests, or real input files. |
auto_installable |
Liquid Agent has an automated install/preparation route for the current runtime class. |
reimplementation_candidate |
The original tool is valuable but not cleanly installable; a small internal proxy or modern reimplementation should be preferred over asking ordinary users to debug legacy dependencies. |
compatibility_proxy_* |
A Liquid Agent internal implementation exists for the practical subset that is safe to reproduce in the main Python runtime. |
A runtime can be installed=True and ready=False. That is normal. For example, PureCN can be installed and smoke-tested, but a real analysis still needs interval coverage tables and normal-database resources.
Users do not need to activate the isolated conda environments manually. Liquid Agent runs external commands through wrappers such as conda run -n liquid_tool_purecn ... from the main agent process.
Registered Runtime Classes¶
| Class | Examples | How Liquid Agent handles it |
|---|---|---|
| Isolated Python env | MethylBERT, CNVkit, FinaleToolkit, MetDecode, BayesCNV, CpGPT, MethylGPT | Creates a dedicated conda environment and checks Python modules or CLI commands. |
| Source checkout | cfDecon, CelFEER, UXM, MethAtlas, cfNOMe, cfDNAFE, EMIT, DeepFRAG | Clones source code under ~/.liquidbiopsy_agent/external_tools/src and runs registered smoke commands when safe. |
| Snakemake workflow | cfDNA UniFlow | Clones the workflow and installs Snakemake in an isolated env; real runs need workflow config and references. |
| Isolated R/Bioconductor env | PureCN, FACETS core | Creates a dedicated conda R environment and validates Rscript plus R package loading. |
| System binary wrapper | modkit route for nanopore methylation | Installs/calls modkit where available; Dorado basecalling remains a user-provided binary/model resource. |
| Reimplementation candidate | CopywriteR on macOS arm64 | Keeps the method visible, records why the legacy install fails, and routes users toward an internal CNV proxy or a maintained modern CNV method. |
Current High-Value Tools¶
| Signal | Runtime/tool | Current project treatment |
|---|---|---|
| Fragmentomics | FinaleToolkit | Isolated Python CLI/runtime. |
| Fragmentomics | cfDNAFE | Source checkout with callable source CLI where compatible. |
| Fragmentomics | cfDNA UniFlow | Snakemake workflow wrapper; real runs need config/reference resources. |
| Fragmentomics | EMIT | Source/model checkout; real runs need EMIT-format end-motif data. |
| Fragmentomics | DeepFRAG | Source checkout; real supervised use needs labels, model resources, and validation design. |
| Methylation | MethylBERT | Isolated Python runtime; real use needs trained checkpoints and read-level methylation inputs. |
| Methylation | cfDecon, CelFEER, UXM, MethAtlas, cfNOMe | Source checkouts; real runs need atlas/marker/reference resources. |
| Methylation | MetDecode | Isolated Python/source runtime; real runs need marker-region methylated/total CpG counts and reference panel. |
| Methylation | CpGPT, MethylGPT | Isolated Python/source runtimes; real runs need compatible checkpoints and matrices. |
| Methylation | Dorado + modkit | modkit can be installed/called; Dorado binary/model and nanopore inputs remain explicit requirements. |
| CNV | CNVkit | Isolated Python CLI/runtime. |
| CNV | PureCN | Isolated R/Bioconductor runtime; real runs need coverage/normal/VCF resources. |
| CNV | FACETS core | Isolated R runtime for core FACETS; full allele-specific workflow needs SNP pileups or platform-specific helpers. |
| CNV | BayesCNV | Isolated Python/source runtime for JAX/numpyro components. |
| CNV | CopywriteR | Legacy install is not reliable on macOS arm64; tracked as a reimplementation candidate with an internal CopywriteR-like CNV proxy. |
Internal Compatibility Proxies¶
Some useful research tools are tied to old Python, old R/Bioconductor, or platform-specific runtime assumptions. When the upstream implementation is small enough, open-source, and algorithmically clear, Liquid Agent can expose a modern internal proxy instead of asking users to repair legacy environments.
Current proxy:
liquid-agent copywriter-proxy \
--input <interval_or_bin_dir> \
--output-dir <output_dir> \
--exclude-regions <targets_or_peaks.bed>
This proxy is intended for first-pass CopywriteR-like off-target/bin-count CNV screening. It performs interval binning, optional target/peak exclusion, depth normalisation, robust gain/loss calls, and simple segment summaries. It is not a full port of the original CopywriteR workflow; publication-grade analyses should still be validated against the original method or a maintained modern CNV workflow such as CNVkit, PureCN, FACETS, or an LPWGS-specific route.
Legacy Or Old-Python Tools¶
When a useful upstream method depends on old Python, old R/Bioconductor, or platform-specific binaries, Liquid Agent records the installation limitation and routes users to an available internal proxy or a maintained modern alternative. Proxy commands state their scope limits and do not claim full upstream equivalence.