Biofact

Every analysis leaves a biofact. Biofact records the evidence behind computational biology workflows — inputs, outputs, commands, versions — as content-hashed, replayable records. Make any analysis, including one run by an AI agent, auditable and reproducible.

Why this exists

AI agents now run real biology: they call BLAST, run variant callers, filter tables, produce figures. But a July 2026 review of 109 agentic bioinformatics systems found the field has a trust gap:

"Planning and tool execution have advanced more rapidly than replayability, provenance, robust scientific assessment, and external validation." — Pham & Hy, arXiv:2607.27556

In plain terms: agents do the science, but nobody can prove what they did or redo it tomorrow and get the same answer. Biofact closes that gap with the smallest possible tool:

• Record — one command wraps your analysis; every input/output gets a SHA-256 content hash, the command line, parameters, exit code, timing, and environment are captured.

• Validate — check later: do the files still exist? Do the hashes still match? (Silent data drift detector.)

• Replay — re-run the recorded commands; identical output hashes = proven reproducibility.

• Report — a structured provenance summary you can cite in a manuscript's code-availability section.

• Agent-native — ships an MCP server, so AI agents (Claude, Cursor, ...) record their tool use through Biofact automatically.

Related MCP server: agent-gate

Install

pip install biofact          # once published on PyPI
# or, from source:
pip install git+https://github.com/biranjan01/biofact

Runtime dependencies: none beyond the Python standard library (plus mcp for the optional agent server). Provenance tooling should never break because a dependency changed.

60-second tour

Wrap any command:

biofact run --name qc-sample-1 --tool seqkit \
  --input reads.fastq --output clean.fastq \
  -- seqkit seq --min-len 50 reads.fastq -o clean.fastq

You get a provenance record. Later — tomorrow, next month, during review:

biofact check    qc-sample-1-<id>.run.json   # do hashes still match?
biofact replay   qc-sample-1-<id>.run.json   # does it still produce the same outputs?
biofact summary  qc-sample-1-<id>.run.json   # the methods-section report

Validate files on their own (catches truncation, FASTQ length mismatches, broken VCF headers, ragged tables):

biofact validate reads.fastq variants.vcf counts.csv

For AI agents (MCP)

Add to your MCP client config (Claude Desktop, Cursor, Claude Code):

{
  "mcpServers": {
    "biofact": {
      "command": "biofact-mcp"
    }
  }
}

Tools exposed to the agent:

Supported file formats (validators)

FASTA · FASTQ · VCF · BED · GFF/GTF · CSV · TSV · JSON — lightweight structural checks (record counts, header sanity, length consistency), not full spec compliance.

What gets recorded

Roadmap

Relationship to existing standards

Biofact is a floor, not a replacement: PROV-O, RO-Crate, and BioCompute Objects are richer, heavier standards. Anything Biofact records can be lifted into them later. Workflow engines (Nextflow, Snakemake, Galaxy) manage execution; Biofact is engine-agnostic evidence layered on top.

Paper

A methods paper is in preparation (paper/paper.md); planned submission to the Journal of Open Source Software after the required 6 months of open development history. Pre-1.0 software — not yet peer reviewed. Cite via CITATION.cff.

Development

git clone https://github.com/biranjan01/biofact && cd biofact
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q            # or: python tests/test_core.py
ruff check src tests

Contributions welcome — especially: replay adapters for common tools, environment capture backends, and benchmark datasets of real workflows.

License & disclosure

MIT. Developed with AI assistance under human direction; all design decisions, testing, and validation are human-owned (disclosed per JOSS AI-usage policy).

Disclaimer: Biofact is a research/reproducibility tool. It does not interpret biological results and must not be used as the sole evidence base for clinical decisions.