Waypoint: Outpost Bio's Open Microbiome Foundation Models

Overview

Outpost Bio open-sourced three artefacts under Apache 2.0, described in Treloar et al., bioRxiv 2026.05.02.722381:

The unifying idea: a microbiome sample is a sentence. Each taxon is one token, tokens are ordered by descending abundance z-score, and the model is trained with next-token prediction. A pretrained checkpoint then supplies sample-level embeddings or a fine-tuning backbone for prediction tasks.

All of it is driven by one CLI, waypoint, with five subcommands: prepare-dataset, embed, finetune, benchmark, pretrain.

When to use

• Embedding 16S/shotgun taxonomic profiles into fixed-size vectors for clustering, visualisation, or a downstream classifier.
• Fine-tuning a Waypoint checkpoint to predict a phenotype, treatment, or continuous readout from community composition.
• Scoring your own microbiome model on Compass with an explicitly recorded protocol.
• Pretraining a taxonomic language model on Atlas or on your own corpus.
• Converting profiler output (MetaPhlAn, Kraken2/Bracken, QIIME 2, MGnify TSVs) into the input format these tools expect.

For small labelled datasets, start with a random-forest baseline and grouped validation. The paper's sample-size crossover is an empirical result from its experiments, not a universal cutoff for using embeddings or a guarantee of performance on a new study.

Setup

pip install "waypoint-bio==1.0.2" "transformers==4.57.6" "peft==0.18.1" "huggingface-hub<1"

The 2026-10-01 review checked the published wheel, GitHub main f45eee6d07a480bfc90f84ab8082bbc969dec15d (1.0.4), and current Hub metadata. Small native CPU/tokenizer tests used Python 3.12, Torch 2.14.1, Transformers 4.57.6, PEFT 0.18.1 and pandas 3.0.6; no pretrained weights or gated rows were downloaded. The package leaves dependencies unbounded: Transformers 5 removes its pretraining logging_dir argument. Keep a separate compatible environment.

Upstream limitations: local TaxonomicTokenizer.save_pretrained() raises NotImplementedError in both reviewed versions, blocking pretrain before training and finetune export when using that local tokenizer. Released 1.0.2 does not merge LoRA adapters or write training logs; GitHub 1.0.4 does. See references/upstream-review.md before training. Training examples below are source-checked templates, not completed scientific runs.

Atlas, Compass, and every Waypoint checkpoint are gated. Access is auto-approved, but you must click through once per repo and then authenticate:

1. Request access on each repo page you need: Waypoint-6m, Waypoint-45m, Waypoint-170m, Atlas, Compass.

2. Authenticate locally:

   hf auth login          # or: export HF_TOKEN=hf_...
   

For 401/403 errors, check token validity, read scope, and approval for the specific repo. The tokenizer loader executes repository code with trust_remote_code=True. Review that code and pin an immutable Hub commit. The upstream CLI has no --revision; download a reviewed snapshot and pass its local path so model, tokenizer and ordering statistics share one revision (see references/python-api.md).

The waypoint data format

Everything except prepare-dataset consumes waypoint format: a .parquet / .csv / .tsv whose rows are samples, with two aligned list-columns plus any label columns you need.

…