docs/USER_GUIDE.md

BioNexus User Guide

BioNexus runs interdisciplinary bioscience analysis: protein/sequence annotation, phylogeny, structure (AlphaFold-style + experimental PDB), docking, molecular dynamics, and NGS pipelines — each step recorded for provenance and published into a reproducible artifact.

Quick start

1. Run an experiment — POST a sequence to /api/pipeline/v2/run (or use the classic /api/pipelines/{pipeline_id}/run on a template). The pipeline persists a job with a full result context.
2. Inspect the AI's work — GET /api/experiments/{job_id}/evidence (evidence graph), /api/experiments/{job_id}/ledger (+ /validate) for the reproducibility ledger, and /api/experiments/{job_id}/paper for a journal-formatted manuscript.
3. Recorded benchmarks — /api/benchmarks lists the curated catalog; POST /api/benchmarks/{benchmark_id}/runs/{job_id} compares a stored result against ground truth (metrics + tolerance).
4. Figures & export — GET /api/figures/{job_id} (publication SVG), /api/figure/formats for the format matrix. Engines export JSON/CSV via /api/engines/{name}/result.
5. Scientific dashboard — /api/dashboard/summary, /api/dashboard/engines, /api/dashboard/datasets (catalog + your uploads), /api/dashboard/runs. Upload your own dataset via /api/dashboard/upload_data, then snapshot it into an engine workspace with /api/datasets/{name}/snapshot.

Engines

Twelve registered engines (GET /api/engines): blast, uniprot, msa, phylo, domains, alphafold, pathway, interpret, evidence, ngs, docking, md. Each implements parse → validate → export → figure and a competing-quality claim.

Reproducibility ledger

Every recorded operation is a carbon: input digest → process → output digest, chained by sha256. ledger/validate never passes an empty chain, a broken hash link, or a step that dropped its input or output.

Deployment notes

• Data is truer when seeds are migrated to latest. Apply supabase/migrations/ in order (009, 010) to the live Supabase project; benchmark seeding degrades gracefully (omit_depth) until 010 is applied.
• The API deploys to a Hugging Face Space; figures are dependency-free SVG.
• Run python scripts/ci_validate.py and python -m pytest before pushing.