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

[![CI](https://github.com/biranjan01/biofact/actions/workflows/ci.yml/badge.svg)](https://github.com/biranjan01/biofact/actions/workflows/ci.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Paper](https://img.shields.io/badge/JOSS-submission%20planned-orange.svg)](paper/paper.md)

---

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

## Install

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

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

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

```bash
biofact validate reads.fastq variants.vcf counts.csv
```

## For AI agents (MCP)

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

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

Tools exposed to the agent:

| Tool | What it does |
|---|---|
| `record_step` | Record one executed step; hashes all listed inputs/outputs |
| `validate_file` | Sanity-check a bioinformatics file's format |
| `check_run` | Verify recorded files still match their hashes |
| `replay_run` | Re-execute the recorded commands, compare output hashes |
| `provenance_report` | Human/agent-readable summary of a run |
| `list_stored_runs` | List everything recorded |

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

| Field | Meaning |
|---|---|
| `inputs` / `outputs` | Path, existence, size, **SHA-256 content hash** |
| `command` | Exact argv, replayable |
| `params`, `exit_code` | Configuration + success signal |
| `started_at`, `ended_at`, `duration_s` | Timing |
| `stdout_tail`, `stderr_tail` | Last 4 KB of output (debuggability) |
| `environment` | Python version, platform, machine, Biofact version |

## Roadmap

| Phase | Deliverable |
|---|---|
| **v0.1 (now)** | Core recorder, replay, drift detection, format validators, MCP server |
| v0.2 | Conda/environment capture, tool-version fingerprinting (`samtools --version` etc.) |
| v0.3 | RO-Crate / PROV-O export; Jupyter notebook cell recording |
| v0.4 | Benchmark: replay success rate on public workflows (BixBench-style) |
| v0.5+ | Paper to [JOSS](https://joss.theoj.org) after 6 months of public development |

## 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](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](CITATION.cff).

## Development

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