Know what your evidence actually warrants.
BioNexus is a warrant-first scientific reliability layer for AI-assisted bioinformatics. It audits analytical assumptions, calibrates evidence strength, caps unsupported claims, verifies execution provenance, and abstains when evidence is insufficient.
Not another AI scientist or workflow platform. BioNexus sits between AI-generated analyses and scientific claims.
Not "the firewall is strict." This:
Before BioNexus — the agent runs it and overclaims:
Request: "Run DE between these two clusters and identify condition-specific genes."
Agent: Done. 2,341 cells vs 3,107 cells. 153 significant genes.
-> Presented as a population-level condition effect.
With BioNexus — the same request is separated into what blocks and what limits:
WARRANT: PERMITTED_WITH_LIMITS (purpose=screening, ceiling=FRAGILE)
Epistemic Context Evaluation:
Design Identifiability: Unpaired, 2 donors/group (within-donor variance unestimated)
Effect-Size Regime: Polygenic moderate effect (requires dispersion shrinkage)
Claim Requested: 'population-level treatment effect' (EXCEEDS EVIDENCE)
Verdict: Compute is fully PERMITTED, but CLAIM is capped to Cohort-Specific Descriptive.
What you CAN still do: run pseudobulk DE, rank candidates, explore within-sample shifts.
What is BLOCKED: 'population-wide causal treatment effect' claim.
Override: allowed (screening purpose) — researcher records why,
and FRAGILE ceiling + blocked claim are preserved.
Rule provenance: Squair et al. 2021 (Nature Comms); Lun & Marioni 2017; Soneson & Robinson 2018.
This is the product: telling you what the evidence warrants. A hard block fires only when an execution invariant is violated (garbage data, model masquerade, uncertified clinical claim) — otherwise BioNexus permits the compute and caps the claim.
A common failure mode of automated validation systems is confusing empirical rules of thumb with universal scientific laws (e.g. dogmatic $N < 3 \to \text{refuse}, N \ge 3 \to \text{valid}$).
In real biological workflows, inferential validity is not a step function at an arbitrary sample size:
-
Design Identifiability: A paired or isogenic design (e.g., treated vs control within the same 2 donors or cell lines) can legitimately identify strong candidate signals with low within-donor dispersion.
-
Effect-Size Regime: A deterministic monogenic knockout (
$\text{Log2FC} > 6, \text{FDR} < 10^{-15}$ ) requires far less replication to rule out technical noise than subtle polygenic shifts ($\text{Log2FC} = 0.3$ ). -
Confounding vs Power: Having
$N=10$ donors with unmodeled batch confounding or extreme uncorrected dispersion does not justify population claims.
BioNexus structures rule enforcement around a 6-stage Context-Conditioned Epistemic Ladder:
flowchart TD
Step1["1. Design Identifiable?\nPaired vs Unpaired / Biological vs Technical / Batch Confounders"] --> Step2["2. Dispersion Estimable?\nEmpirical Bayes Shrinkage / Degrees of Freedom / Outlier Robustness"]
Step2 --> Step3["3. Uncertainty Quantified?\nWithin-group vs Between-donor Variance / Posterior Confidence Bounds"]
Step3 --> Step4["4. Power & Effect-Size Regime?\nObserved Log2FC vs Minimum Detectable Effect at Nominal FDR"]
Step4 --> Step5["5. Claim Class Evaluated?\nDescriptive Ranking → Sample Association → Population Generalization → Causal Mechanism"]
Step5 --> Step6["6. Evidence Ceiling Assigned\nROBUST / SUPPORTED / FRAGILE / ABSTAIN"]
Scientific consensus evolves as experimental modalities and statistical models advance. BioNexus provides an open, auditable governance loop:
-
Scientific Rule Catalog (
review/SCIENTIFIC_RULE_CATALOG.json): Explicitly documents the context conditions, uncertainty parameters, biological exceptions, and literature citations for every rule. -
Rule Challenge Mechanism: Researchers can submit formal Scientific Rule Challenges via GitHub Issues and Discussions to propose counterexamples, novel biological contexts, or updated empirical bounds.
BioNexus was upgraded from "when not to compute" to "what the evidence warrants". Six mechanisms make that real:
| Pillar | What it does | Key API |
|---|---|---|
| 1. Invariant vs Warrant | Splits every rule into an execution invariant (safety/integrity — must block) or a warrant constraint (epistemic — caps the claim, never blocks legal compute). | RuleCategory, RuleClassification |
| 2. Evidence Model | Evidence strength is assessed only from evidence facts (replication, sample design, confound controls, provenance…) — purpose decides the requirement the evidence must clear, never the evidence value: exploratory requires ≥ PRELIMINARY, confirmatory ≥ ROBUST, clinical ≥ REPLICATED + external validation. Unspecified purpose leaves sufficiency undecided — BioNexus does not assume exploratory for you. |
assess_evidence, evaluate_sufficiency, UseRequirement |
| 3. Rule Provenance | Every rule carries evidence-backed provenance (DOIs/URLs), a consensus level, and known exceptions — loaded from an auditable registry, not hardcoded opinion. | RuleProvenance, load_rule_registry |
| 4. Researcher Override | Professionals may proceed past a soft warrant block, but must record why, what limits remain, and which claims still cannot be made. Hard invariants are never overridable. | create_override_record, OverrideRecord |
| 5. BCTK Diagnostic Kit | Target-bound development diagnostics for third-party agents, plugins, workflows, and packages. Certification and badge issuance are suspended pending independent evidence. | bctk test, bionexus conformance test, BNS-020 |
| 6. Evidence Debt Ledger | Traces scientific shortcuts, uncalibrated thresholds, and domain mismatches across the claim DAG with optimal repayment scheduling. | bionexus debt audit, bionexus debt payoff, BNS-021 |
The old binary PERMITTED / REFUSED is now a spectrum: PERMITTED · PERMITTED_WITH_LIMITS (soft blocks overridden) · REFUSED (hard invariant violated).
Similar to the OpenTelemetry (OTel) compliance ecosystem, BioNexus explicitly distinguishes between using BioNexus and being BioNexus-Conformant: BioNexus does not force researchers or agent developers to use BioNexus's internal code; rather, if any Agent, Plugin, Workflow, or Analysis Package claims BioNexus Conformance, it must machine-provably satisfy the Scientific ABI v1 across 8 core dimensions.
# Test any plugin, skill, python module, or package:
bctk test my-plugin
# or
bionexus conformance test my-pluginSee the full BCTK Developer Guide and BNS-020 Specification.
In software engineering, teams manage Technical Debt rather than publishing an arbitrary "Code Quality: 83%".
BioNexus introduces Evidence Debt (BNS-021) for computational biology and AI discovery: Instead of a vanity score, BioNexus structures deferred verifications, heuristic shortcuts, uncalibrated thresholds, and domain mismatches across the project dependency DAG.
Claim 17 (Target gene CD274 upregulated in Exhausted CD8+ T cells)
↓
Claim 12, Claim 7, Claim 4, Claim 1, Claim 19, Claim 20 (6 other claims)
↓
TRANSFORM-ANNOTATION-X (Heuristic gating on tumor infiltrate)
↓
Atlas Reference Domain Mismatch (PBMC reference)
Fixing TRANSFORM-ANNOTATION-X yields a 70.0x Payoff Multiplier, simultaneously amortizing Evidence Debt for 7 downstream claims and upgrading the project maturity floor from FRAGILE to SUPPORTED!
# Audit project evidence debt
bionexus debt audit .
# Compute optimal repayment schedule ranked by scientific leverage
bionexus debt payoff .
# Visual Mermaid dependency DAG
bionexus debt graph .See the full Evidence Debt Developer Guide and BNS-021 Specification.
The deepest decoupling: purpose decides the evidence requirement, never the evidence value. A study with 10 donors/group, pre-registration, adequate power, and an independent replication carries ROBUST evidence whether the researcher calls it exploratory or confirmatory — and weak data does not acquire a REPLICATED standing because someone declares a clinical purpose. Three objects make this explicit:
| Object | Question | Depends on |
|---|---|---|
| EvidenceAssessment | How strong is the evidence? | Evidence facts only (declared factors + active violations). Purpose- and policy-independent. |
| ClaimContext | What does the researcher want to claim? | Claim class: descriptive → association → population effect → mechanistic → causal → clinical actionability. |
| UseRequirement | How much evidence does the intended use demand? | Purpose + claim class composed — the only place purpose enters. |
The verdict compares them — evaluate_sufficiency returns WARRANTED, WARRANTED_WITH_LIMITS
(documented ack; the bar never moves), or NOT_SUFFICIENT_FOR_INTENDED_USE with an explicit gap list:
from bionexus import (
assess_evidence, evaluate_sufficiency, ClaimClass, ClaimContext,
PurposeContext, ResearchPurpose,
)
# Evidence is what it is, whatever the purpose:
evidence = assess_evidence(satisfied_factors=[
"sample_design", "confound_controls", "sensitivity_analysis",
"backend_fidelity", "provenance",
]) # -> ROBUST under every purpose
# ROBUST evidence + population-effect claim + confirmatory use -> WARRANTED
suff = evaluate_sufficiency(
evidence=evidence,
purpose_context=PurposeContext(purpose=ResearchPurpose.CONFIRMATORY),
claim_context=ClaimContext(claim_class=ClaimClass.POPULATION_EFFECT),
)
# SufficiencyVerdict.WARRANTED
# SUPPORTED evidence + clinical use -> NOT_SUFFICIENT_FOR_INTENDED_USE
# (requires REPLICATED + external_validation + regulatory_context)BioNexus strictly separates two objects that must never be conflated:
WarrantAssessment (science — policy-independent) PolicyDecision (deployment posture)
───────────────────────────────────────────────── ─────────────────────────────────
claim_maturity · evidence_ceiling · unsupported_ ALLOW · ALLOW_WITH_ACK · ALLOW_WITH_LIMITS
claims · residual_uncertainty · rule_basis REQUIRE_OVERRIDE · BLOCK · ESCALATE
The assessment answers “what is this evidence worth?” and is computed only from the evidence facts (declared factors, active violations) — purpose sets the use requirement, never the evidence value — so it is identical in every lab. The policy decision answers “does BioNexus intervene, and how?” For n=1 donor/condition, every lab sees the same science:
Scientific assessment (all labs): ceiling = FRAGILE · population_level_inference unsupported
Policy action: SHADOW → ALLOW_WITH_ACK (proceed; warning recorded)
DISCOVERY → ALLOW_WITH_LIMITS (exploratory/screening; no separate override)
ENFORCED → BLOCK (remedy the violation first)
| Profile | Intervention on a warrant violation | Scientific assessment |
|---|---|---|
| shadow_audit | ALLOW_WITH_ACK — proceed, warning on the EvidenceCard | unchanged (ceiling still applies to every claim) |
| discovery_lab (default) | Exploratory/screening: ALLOW_WITH_LIMITS; confirmatory/causal: REQUIRE_OVERRIDE | unchanged |
| enforced_lab | BLOCK — even under override | unchanged |
from bionexus import route_scientific_intent
decision = route_scientific_intent(
"Run differential expression between conditions",
data_metadata=meta,
research_purpose="screening",
lab_policy="shadow_audit", # or "discovery_lab" / "enforced_lab"
)
card = decision.evidence_card_template
card.details["warrant_assessment"] # identical across profiles
card.details["policy_decision"] # the only thing that variesTwo guardrails keep this honest in both directions:
-
Policy decides intervention, never evidence value. The same data yields the same
WarrantAssessment(ceiling, unsupported claims, residual uncertainty) under shadow, advisory, and enforced — asserted by the test suite as the decoupling invariant. -
Execution invariants are never relaxed.
INVARIANT_SAFETYrulesESCALATEto human/regulatory review andINVARIANT_INTEGRITYrulesBLOCKunder every profile; the resolved profile name and both objects are always written to the EvidenceCard for audit. -
Friction is observable and risk-scaled.
PolicyDecisionrecordsfriction_levelandrequires_user_action. Low-risk discovery spends only a record-only acknowledgement; a user-supplied override is still retained, while confirmatory/causal gaps require one and clinical/integrity boundaries remain non-overridable.
BioNexus is two planes with hard boundaries — the reliability layer IS the product, and frontier biology is reference implementation, never a product layer (full matrix):
| Plane / Layer | Contains |
|---|---|
| BioNexus Core · core | BNS spec series · Biological Capability ABI · Failure Taxonomy (BN-Fxxx) · Fail-Closed Engine · Evidence Model |
| BioNexus Core · audit | preflight · audit · verify |
| BioNexus Core · conformance | capability certification (flagship track) · backend identity conformance (declared_backend == observed_backend, machine-provable, BN-F010) · host conformance · BioFailureBench |
| Capability Plane · stable reference packs | single-cell · spatial · reproducibility |
| Capability Plane · frontier reference packs | foundation models · cluster/big data · tangram · perturbation/closed-loop (opt-in only) |
Explicitly not in scope, ever: planner, memory, multi-agent, chat UI, cloud workspace, notebook replacement, compute service, agent marketplace, or a frontier capability promoted to a product layer.
Current phase — capability freeze: no new horizontal capabilities (protein / clinical / additional omics tools). Development concentrates on certifying the three flagships — scrna.pseudobulk_de, scrna.annotation_evidence, spatial.inference_validity — to genuine CERTIFIED status; three certified flagships prove the warrant-engine thesis better than a broad uncertified catalog.
Literature, Databases, NGS, Sequence, Structure, and Slide plugins are peer capabilities selected by the host or researcher. BioNexus does not orchestrate or duplicate them; it passively audits their completed outputs:
external capability -> content-bound intake -> provenance/semantic audit
-> explicit reviewed edges + context/duplicate audit
-> Warrant + Audit + EvidenceCard -> Human Scientific Adjudication
The external-evidence-audit wrapper implements
bionexus.external-evidence-envelope.v1. It binds each result to declared
producer/tool context, the originating request, exact payload SHA-256, and
family-specific interpretation metadata. A valid intake remains UNASSESSED
and context_only: a paper, database record, second method, sequence view,
structure view, or slide observation is never automatically promoted to
independent validation. See the cross-plugin collaboration contract.
For multi-source claims, bionexus.ecosystem-claim-packet.v1 requires one
explicit, receipt-bound adjudication per result and a named human decision
owner. BioNexus detects duplicate payloads, blocks declared scope conflicts,
preserves contradictions, and emits Warrant + Audit + EvidenceCard + Ledger;
it never infers evidence relationships or changes
PENDING_HUMAN_DECISION into an autonomous verdict.
bionexus.human_adjudication closes that loop without transferring scientific
authority to AI. A named decision owner may record ACCEPT_FOR_EXPLORATION,
ACCEPT_WITH_LIMITS, DEFER_PENDING_EVIDENCE, or REJECT against the exact
assessment SHA-256. The decision receipt binds rationale, intended use,
conditions, acknowledged limits, and addressed contradictions. BioNexus checks
the record and non-bypassable boundaries only: adjudication never promotes the
machine-assessed maturity, rewrites the warrant, or turns a structurally
BLOCKED packet into acceptance.
Hosted peer MCP servers remain listed in the canonical compatibility catalog but are not bundled into BioNexus manifests by default, preventing duplicate tool registration when dedicated ecosystem plugins are installed.
Functional plugins, prompt templates, and agent tool wrappers are easily duplicated. An expert-annotated, ground-truth biological failure corpus with deterministic traps and fail-closed invariants is a defensible scientific evaluation and data flywheel moat.
BioNexus formalizes Failure Taxonomy v1 (bionexus.failure_taxonomy.v1) across 12 core failure modes (BN-F001 .. BN-F012) and links them to 38 canonical seed traps (BF-001 .. BF-038) across 4 categories:
DATA_INTEGRITY: Assay-state confusion (BN-F001), Identifier mismatches (BN-F004), Cross-database contradictions (BN-F008), Missing spatial provenance (BN-F009).INFERENTIAL_DESIGN: Pseudoreplication (BN-F002), Missing FDR control (BN-F005), Invalid model assumptions (BN-F006), Parameter instability (BN-F007).SEMANTIC_CLAIM: Unsupported annotations (BN-F003), Claim inflation (BN-F011), Unexecuted maturity claims (BN-F012).SYSTEM_DEGRADATION: Backend masquerading (BN-F010).
Scientists can lint and contribute new failure traps using standardized JSON Schema and CLI validation:
# Display corpus coverage and data flywheel metrics
bionexus bench stats
# Validate entire corpus integrity and taxonomy linkage
bionexus bench validate
# Output community trap submission template
bionexus bench template -o new_trap.yaml
# Validate a community trap submission file
bionexus bench validate-trap new_trap.yaml
# Inspect Capability x Failure Mode mapping matrix
bionexus failures matrixBioNexus does not invent a proprietary research-data standard. Run capsules and Claim–Evidence Ledgers export through published community standards (bionexus interop ro-crate|bco|wfrun-crate|check):
Claim–Evidence Ledger ──> W3C PROV-O ──┬── RO-Crate 1.1 (+ Workflow Run Crate profiles)
Run Capsule ─────────────────┼── Workflow Run RO-Crate Research Object bundle
Run Capsule ─────────────────┴── BioCompute Object (IEEE 2791-2020)
bionexus interop wfrun-crate <run> --out <dir> packages a sealed run capsule into a standard Workflow Run RO-Crate Research Object: the actual input bytes, software (engine + pinned packages), the execution as a schema.org CreateAction, recorded per-step executions (Provenance Run Crate), output artifacts, the EvidenceCard, and any adjacent Claim–Evidence Ledger — conforming to the profile chain Process/Workflow/Provenance Run Crate 0.5 + Workflow RO-Crate 1.0.
Institutional pipelines (Galaxy, DNAnexus, Seven Bridges, WorkflowHub) can ingest BioNexus outputs today without adopting anything else from BioNexus. Exports are deterministic, offline, and validated before they are written: an export that fails structural validation is never written, and the materialized crate is re-verified on disk (fail-closed interop, BNS-IO-004/BNS-IO-014). CI additionally builds a sealed fixture and requires the official roc-validator==0.11.2 to accept the complete inherited profile chain at REQUIRED severity. The hash-bound THIRD_PARTY_TOOL_VALIDATED receipt is technical conformance evidence, not certification, endorsement, adoption, or scientific validation (BNS-IO-010).
Honest positioning (bionexus standards): BioNexus is not an industry standard and does not claim to be one. The BNS series is an implementation proposal — discussable, criticizable, contributable — with the GA4GH AI Work Stream as the primary engagement window (standards engagement). Alignment statuses are machine-readable and honest: implemented (RO-Crate, Workflow Run Crate, BCO, PROV-O) · aligned (Bioschemas) · tracked (nf-core, GA4GH AI Work Stream, ELIXIR, scverse, Bioconductor, WorkflowHub). nf-core remains tracked, not proposal, until a permanent public submission/discussion receipt exists.
Scientific meaning exchange (BNS-019) is now an independently releasable, language-neutral contract under standards/scientific-semantic-conventions/. The normative registry, JSON Schemas, conformance fixtures, compatibility policy, and SHA-256 release manifest no longer live inside the Python product. Development 0.1.0 is an executable proposal, not evidence of adoption or endorsement.
For workflows, the integration boundary is now explicitly zero-touch: Workflow Run RO-Crate records what ran; an external BNS-019 sidecar annotates only individually hash-bound artifacts whose semantics were explicitly declared. BioNexus does not require nf-core pipeline changes and does not infer scientific meaning from samplesheets, filenames, or successful execution.
Spatial Empirical Gold is deliberately narrower: BioNexus calibrates the Alternative Explanation Battery only for Xenium, CosMx, and MERSCOPE. The program contract forbids platform pooling, synthetic production evidence, donor/FOV leakage, universal fallback thresholds, and automatic approval. The current registry contains zero real studies and zero approved profiles; all 36 platform × metric cells remain incomplete_not_claim_ready.
Install BioNexus into your preferred environment and complete a first audit:
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ CHOOSE YOUR INSTALLATION PATH │
├───────────────────────────────┬───────────────────────────────┬─────────────────────────────┤
│ 🤖 PATH A: AI Coding Agents │ 🚀 PATH B: One-Click Local │ 🐍 PATH C: Python pip / uv │
│ (Codex, Claude, Cursor) │ (Windows, macOS, Linux) │ (Developers, HPC, CLI) │
└───────────────────────────────┴───────────────────────────────┴─────────────────────────────┘
Plugin installation does not install the Python package. Running BioNexus
analyses, doctor.py, or the local stdio MCP server requires Python 3.10+.
Add the repository marketplace:
codex plugin marketplace add HERRY423/BioNexus --ref mainRestart the ChatGPT desktop app, open the Plugins Directory, select BioNexus Marketplace, and install BioNexus. Repo marketplaces are for development, team distribution, and testing; they are separate from the universal public Plugins Directory.
When the public submission is approved and published, search the universal Plugins Directory for BioNexus instead; one public listing is shared by supported ChatGPT and Codex surfaces.
claude plugin marketplace add HERRY423/BioNexus
claude plugin install bionexus-reliability@bionexus-marketplaceStart a fresh session after installation:
claudeTry this prompt in either host:
Use BioNexus to audit this differential-expression result.
1. Identify the experimental unit.
2. Check for pseudoreplication and missing biological replicates.
3. Separate computational support from biological interpretation.
4. State the maximum warranted claim and every blocking evidence gap.
5. Abstain rather than invent missing provenance, labels, or validation.
For a local environment check after cloning the repository:
python scripts/doctor.pySee the plugin distribution guide for manifest validation, workspace distribution, and public submission checklists.
In Cursor Settings → Features → MCP Servers → Add New MCP Server:
-
Name:
bionexus -
Type:
command(stdio) -
Command:
python scripts/local_mcp_server.py
Or add directly to project .cursor/mcp.json:
{
"mcpServers": {
"bionexus": {
"command": "python",
"args": ["${workspaceFolder}/scripts/local_mcp_server.py"]
}
}
}
BioNexus includes zero-configuration automated initializers that detect your OS, CPU, and GPU (NVIDIA CUDA / Apple Silicon MPS / CPU) and build an optimized environment:
-
🪟 Windows (Double-Click or PowerShell):
Double-click
setup.bator run in PowerShell:.\setup.ps1
-
🍏 macOS / 🐧 Linux (Bash):
chmod +x setup.sh && ./setup.sh
For existing Conda or Python 3.10+ environments:
# Clone the repository
git clone https://github.com/HERRY423/BioNexus.git
cd BioNexus
# 1. Base install
pip install -e .
# 2. Standard Single-Cell & Spatial Toolchain (Recommended)
pip install -e ".[goldchain,spatial,allotrope,mcp]"
# 3. High-Speed Full Installation with uv
uv pip install -e ".[all]"
| Extra Tag | Key Included Packages | Analytical Capabilities |
| :--- | :--- | :--- |
| [goldchain] | scanpy, anndata, pydeseq2, harmonypy, leidenalg | scRNA-seq QC, batch correction, marker scoring, DESeq2 |
| [scverse] | scvi-tools, torch, optuna + goldchain | Deep generative modeling (scVI/scANVI), VAE latent space |
| [spatial] | squidpy, anndata | Spatial transcriptomics, Moran's I SVGs, spatial graph stats |
| [survival] | lifelines | Clinical survival analysis (Kaplan-Meier, log-rank, Cox PH) |
| [plm] | transformers, torch | Protein language models (ESM-2 zero-shot variant scoring) |
| [structure] | abnumber, biotite | IMGT antibody numbering, CDR parsing, Kabsch structural alignment |
| [biologics] | ViennaRNA | RNA secondary structure MFE & therapeutic mRNA design |
| [allotrope] | allotropy, polars, openpyxl, pypdf | Analytical instrument raw file conversion to Allotrope ASM JSON |
| [mcp] | mcp>=1.0.0 | Official Model Context Protocol Python SDK integration |
| [all] | All optional stacks + dev tools | Complete biomedical bioinformatics & AI capability suite |
You keep using Scanpy, Seurat, Bioconductor, Claude, Codex, and Cursor. BioNexus does not replace any of them — it evaluates whether the scientific claims they produce are warranted. The enforcement surface has three entry points; each returns a warrant, not just a pass/fail: execution invariants are blocked outright, while warrant constraints cap the claim and disclose the ceiling. Three high-frequency entry points:
bionexus preflight sample.h5ad --intent differential-expression
=== BioNexus Preflight ===
INTENT
Single-Cell Pseudobulk Differential Expression (scrna.pseudobulk_de)
DATA STATE
[OK] matrix state: raw integer-like counts present
[!!] biological samples: 8 donors across 2 conditions; minimum 2 donors in a group
RISKS
[!!] BN-F006: condition strongly confounded with 'donor' (1:1 design)
DECISION
ABSTAIN -> REFUSE
ALLOWED
- at most: Exploratory within-sample marker ranking, explicitly not condition DE
FORBIDDEN CLAIM
- causal_interaction: Claiming causal molecular interaction or regulation from correlational evidence
- maturity above 'SUPPORTED' without external validation
REMEDY
- Add biological replicates that decouple condition from 'donor' or perform an explicit sensitivity analysis
Exit codes encode the verdict: 0 proceed (incl. capped/degraded), 1 refused or claim-blocked, 2 missing evidence.
bionexus audit analysis.ipynb
Deterministic static rules screen the canonical trap classes — pseudoreplication, raw/log confusion, missing FDR, batch/condition confounding, wrong statistical unit, annotation without evidence, circular marker validation, missing negative controls, spatial coordinate substitution, parameter instability, overclaimed causality, backend substitution, and unexecuted code claims. Every finding cites its rule id, taxonomy failure id (BN-Fxxx), evidence line, and remedy. Honest scope: static rules have false negatives — absence of findings is not proof of validity.
bionexus verify results/ # reads the Claim–Evidence Ledger (BNS-012)
Each claim is re-resolved fail-closed against its evidence graph and the capability's ceiling; causal language beyond the evidence class is flagged as not warranted:
CLAIM [CLAIM-DEMO-017]
CXCL13+ T cells are enriched in tumor
Evidence:
[OK] EVID-DA: differential abundance test on independent donors (method_run, SUPPORTED)
[~] EVID-SENS: context: parameter sensitivity: borderline at k=30 (statistical_result, FRAGILE)
Warrant: SUPPORTED
Not warranted:
- "causal_interaction: ..." (forbidden)
Verify your installation and inspect active backend tiers at any time:
python scripts/doctor.py
Example output from a fully provisioned environment (see bionexus doctor in src/bionexus/cli.py for the exact format):
==============================================================================
BioNexus Environment Doctor
==============================================================================
Plugin Version: 0.10.0
Tier: full
Active Analytical Capabilities:
[PASS] core_ready : ready
[PASS] scverse_ready : ready
[PASS] scvi_ready : ready
[PASS] spatial_ready : ready
[PASS] survival_ready : ready
[PASS] nextflow_ready : ready
==============================================================================
Missing backends are reported as [MISSING] ... : not installed and lower the tier to degraded (or refuse when the core stack is absent). Manifest drift checking is a separate command: bionexus registry --check.
Test BioNexus immediately in your AI coding environment:
"Use BioNexus to inspect this workspace environment and report which biological workflows and database tools are currently available. Adhere strictly to the non-negotiable honesty policy."
"Using the BioNexus MCP database tools, fetch the protein details for human TP53 (UniProt 'P04637'). Retrieve its known domains, AlphaFold 3D structure pLDDT confidence, and associated Reactome pathways."
"Inspect my single-cell dataset 'sample.h5ad'. Execute MAD-based outlier detection, run Leiden clustering with numeric labels only (do not guess cell types), identify marker genes, and generate a 7-dimensional EvidenceCard."
BioNexus is governed by a normative, machine-enforced scientific contract published in spec/ — nine RFC 2119-style documents with stable requirement IDs (BNS-XX-nnn) and live verification hooks:
| Spec | Governs |
|---|---|
| BNS-001 | Capability Contract & Biological Capability ABI |
| BNS-002 | Input semantic invariants (raw vs normalized, coordinates, cell types) |
| BNS-003 | Execution fidelity & gold backends |
| BNS-004 | EvidenceCard 2.0 maturity ladder & calibration |
| BNS-005 | Deterministic abstention & degraded advisories |
| BNS-006 | Provenance & reproducibility sidecars |
| BNS-007 | Parameter sensitivity & cross-method concordance |
| BNS-008 | Host agent conformance (Claude / Codex / any agent) |
| BNS-009 | Capability lifecycle, frontier graduation, deprecation |
| BNS-010 | Capability certification: 14 evidence criteria, 4 tiers |
| BNS-011 | Scientific failure taxonomy (BN-F001..F012) |
| BNS-012 | Claim–Evidence Ledger (JSON / PROV-O JSON-LD) |
| BNS-013 | Scientific Assertion Firewall: preflight / audit / verify |
| BNS-014 | BioFailureBench: the scientific trap corpus (BF-nnn) |
| BNS-015 | Flagship certification: 3 externally-validated CERTIFIED capabilities |
| BNS-016 | Standards interoperability: RO-Crate / Workflow Run Crate / IEEE 2791 BCO; product scope boundary |
The Biological Capability ABI (bionexus abi show <id>): every capability projects to a stable Scientific ABI — input contracts (allowed matrix states, coordinate types), forbidden claims, execution references, validation policy, evidence ceilings, and provenance requirements. Any host agent connecting to BioNexus inherits this boundary and cannot bypass it.
Fail-closed philosophy (bionexus prevent "<query>"): knowing what the evidence warrants is a scientific capability. Fail-closed now means two things: hard execution invariants (missing evidence → ABSTAIN, identifier corruption → REFUSE, model masquerade → BLOCK) still gate the compute, while soft warrant constraints (weak statistics, thin replication, unvalidated assumptions) permit the compute but cap the claim — violated assumption → CAP CLAIM MATURITY, absent external validation → CAP EVIDENCE LEVEL, unspecified purpose → sufficiency undecided for any intended use. The scarcest BioNexus API is not run() — it is the honest warrant.
Capability certification (bionexus certification): skills deepen through evidence tiers — CERTIFIED (all 14 criteria: backend, input contract, invariants, failure modes, positive/negative/adversarial tests, public reference dataset, independent ground truth, parameter perturbation, degradation test, provenance test, cross-host test, external reviewer), VALIDATED, EXPERIMENTAL, CONNECTOR-ONLY. Tiers are computed from recorded evidence, never asserted; the blocking-criteria list per capability is the published roadmap to 10 CERTIFIED.
Flagship certification track (BNS-015): three CERTIFIED capabilities with independent external validation outweigh ten self-tested certifications. The flagship set concentrates effort on the three highest-frequency failure surfaces — scrna.pseudobulk_de (cell ≠ biological replicate), scrna.annotation_evidence (how much evidence backs a cell-type label), and spatial.inference_validity (can a spatial conclusion survive its alternative explanations). The four external criteria (public dataset, independent ground truth, cross-host test, external reviewer) cannot be satisfied by the implementer alone — that is the point.
Independent Validation Network (BNS-023): the flagship external-validation quota — ≥ 3 independent datasets × ≥ 2 external labs × ≥ 1 non-author reviewer per capability — is computed from hash-verified artifacts via bionexus ivn status and published as an open, append-only, signed public ledger portal (docs/ivn/index.html on GitHub Pages). Publishing an honest, unfilled ledger with standardized submission templates is our active external recruitment engine ("空账本 + 明确的填法，本身就是对外招募工具") and the only scientific moat that automatically deepens over time. Annotation evidence must span cross-disease / cross-tissue / cross-technology contexts; spatial evidence must carry independent pathology or segmentation truth; threshold/calibration profiles authorize a positive warrant only when frozen on held-out contexts (bionexus ivn freeze-profile / authorize). Every gate fails closed: author-associated datasets, registered-but-unverified frameworks and reviewer slots, tampered artifacts, and unfrozen profiles never count. Protocol, public ledger, and RFV recruitment guides: docs/independent-validation-network.md.
Scientific failure taxonomy (bionexus failures list): twelve failure modes (BN-F001 assay-state confusion … BN-F012 unexecuted maturity claim), each with definition, detection rule, required fail-closed behavior, acceptable degradation, and benchmark coverage. Since BioFailureBench, all twelve modes carry wired detection and passing benchmark traps — the three formerly-open gaps (BN-F004 identifier mismatch, BN-F005 missing FDR, BN-F008 cross-database contradiction) are closed. This ontology is BioNexus's durable asset.
Claim–Evidence Ledger (bionexus ledger): claims as auditable dependency graphs (supported_by / contradicted_by / depends_on → fail-closed status resolution), persisted as JSON and projectable to PROV-O JSON-LD. Deliberately a data structure, not a graph platform. bionexus verify is its productized form.
BioFailureBench (bionexus bench validate / bionexus eval --suite biofailurebench, BNS-014): a scientific trap corpus that does not test "can the AI answer biology questions" — it tests whether the AI realizes a conclusion does not stand on its evidence — or that an analysis should not have been run at all. Every trap carries eight fields (data, intended analysis, hidden flaw, expected detection, allowed computation, forbidden claim, remediation, reference), links into the BN-Fxxx taxonomy, and runs identically on any host (Claude, Codex, Cursor, Biomni, future agents). Software, skills, and prompts are easy to copy; an expert-maintained trap corpus with ground truth is not. Current state: 26 traps (23 gating, all passing deterministically; 3 frontier known limitations), covering all 12 taxonomy modes including a positive control so the bench cannot degrade into an all-refusal benchmark.
Honest calibration (BNS-LC-004..006): the benchmark separates the gating track (guaranteed behavior, drives CRI) from the frontier track (known_limitation probes, reported with honest pass/fail). A gating-only 100% is explicitly not a calibration claim; calibration spans the union. Current honest state: gating 61/61 attempted (65 total, 4 L3 skipped no-backend) · frontier 7/14 · union 90.7% · union macro-F1 90.1% — see evals/reports/benchmark_report.md.
BioNexus enforces a strict distinction between Execution Fidelity (whether official algorithms executed) and Scientific Evidence Quality (statistical power, input integrity, parameter sensitivity, and external validation).
Every biological output is packaged with a deterministic EvidenceCard
and a synthesized ConclusionMaturity. Execution state, evidence
dimensions, claim ceiling, limitations, and external-validation status remain
separate fields; a successful run cannot by itself raise scientific maturity.
| Skill Directory | Primary Backend | Evidence Grade | Non-Negotiable Scientific Honesty Rule |
| :--- | :--- | :--- | :--- |
| single-cell-rna-qc | scanpy + pydeseq2 | Grade A | Clusters remain numeric only. Never invent cell-type annotations without trained reference models. |
| spatial-transcriptomics | squidpy | Grade A | Requires physical spatial coordinates. Refuses analysis if coordinates are missing. |
| scvi-tools | scvi-tools, torch | Grade A | Deep generative modeling on raw counts. Refuses if GPU/torch dependencies are missing. |
| nextflow-development | nextflow, nf-core | Grade A | Validates FASTQ/BAM schema and profile configurations before generating launch scripts. |
| instrument-data-to-allotrope | allotropy | Grade A | Converts raw analytical instrument outputs (27+ vendors) into standardized Allotrope ASM JSON. |
| provenance-and-audit | bionexus.provenance | Grade B | SHA-256 dataset hashing and W3C PROV-O JSON-LD tracking without claiming 21 CFR Part 11. |
| external-evidence-audit | bionexus.ecosystem_intake + bionexus.ecosystem_claim | Grade B | Audits host-supplied results and explicit multi-source adjudications; intake remains UNASSESSED, duplicate evidence is not double-counted, and the final decision is always human-owned. |
| clinical-cohort-analysis | lifelines (optional) + scipy | Grade C | Uses Cox PH when lifelines is present; explicitly labels event-rate ratios as Grade C fallback. |
| variant-interpretation | local ACMG combiner + PWM splice | Grade C | Deterministic ACMG combination heuristics, strictly Research-Use-Only (RUO). Explicitly disclaims CLIA/CAP certification. |
| protein-structure-analysis | RCSB/AlphaFold HTTP + Kabsch | Grade C | Uses exact Kabsch superposition on fetched coordinates; geometry heuristics are labeled Grade C, not gold-standard force fields. |
| protein-language-models | ESM-2 (opt-in) / BLOSUM62 | Grade C | Requires explicit user opt-in (BIONEXUS_ALLOW_ESM=1); never masquerades BLOSUM as ESM. |
| biologics-design | abnumber (optional) + sequence motifs | Grade C | Uses abnumber for IMGT numbering when installed; regex/motif fallbacks are explicitly labeled Grade C heuristics. |
| multiome-integration | sklearn ExtraTrees | Grade C | Co-expression heuristics only — explicitly not SCENIC+/GRNBoost2; disabled by default (opt-in via SKILL.legacy.md). |
Grade provenance: Evidence grades in this table mirror the canonical Single Source of Truth (
bionexus.registry.yaml,skills.canonical+skills.heuristics). Overclaims are rejected in CI bytests/unit/test_readme_consistency.py. Grade A = community gold-standard backend executed; Grade C = labeled local heuristic; optional-backends skills degrade honestly to C when the backend is absent.
BioNexus exposes a small local MCP compatibility surface. Dedicated ecosystem plugins should provide literature, database, analysis, and visualization capabilities; BioNexus audits their returned evidence through the host.
Zero API keys required for all core endpoints:
-
Core Local Unique Tools (Default Active — 9 Tools):
-
Proteins & Structures:
search_uniprot,search_alphafold,search_pdb -
Genomics & Regulation:
search_ensembl,search_gnomad,get_gene_expression(GTEx),search_geo -
Pathways & Networks:
search_reactome,search_string
-
-
Workflow Resources & Prompts (Always Active):
-
6 production YAML workflows/configs (
bionexus://workflows/...,bionexus://configs/...) -
6 structured bioinformatic prompts (
drug_target_analysis,variant_pathogenicity, etc.)
-
-
Hosted Fallbacks (Opt-in Disaster Recovery via
BIONEXUS_LOCAL_HOSTED_FALLBACKS=1):search_pubmed,get_pubmed_article,search_biorxiv,search_chembl,search_opentargets,search_clinical_trials,search_cosmic(hidden by default to avoid duplicate tool routing with cloud endpoints)
The SSOT retains known hosted endpoints for compatibility checks, but entries
marked bundle_with_plugin: false are excluded from generated Agent Plugin,
Codex, and Claude MCP manifests. Install the relevant peer plugin separately;
then pass its result into external-evidence-audit.
To raise rate limits or connect enterprise lab platforms, copy .env.example to .env and run:
python scripts/auth_helper.py --status
All client configurations across Codex, Claude, Cursor, and Python packages are deterministically compiled from bionexus.registry.yaml:
graph TD
SSOT["bionexus.registry.yaml<br/>Canonical Registry"] --> Compiler["scripts/registry_compiler.py<br/>SSOT Compiler Engine"]
Compiler --> C1["plugin.json<br/>Agent Plugins 1.0"]
Compiler --> C2[".claude-plugin/plugin.json<br/>Claude Code / Desktop"]
Compiler --> C3[".codex/config.json<br/>OpenAI Codex Platform"]
Compiler --> C4["mcp.json & .mcp.json<br/>Local MCP + explicitly bundled endpoints"]
Compiler --> C5["marketplace.json<br/>Plugin Catalog Manifests"]
# Generate all platform manifests
python scripts/registry_compiler.py --generate
# Verify zero drift in CI/CD (fails if files were manually edited out of sync)
python scripts/registry_compiler.py --check
# Validate URL syntax and connectivity
python scripts/registry_compiler.py --validate-endpoints
BioNexus is continuously tested on Linux, Windows, and macOS with Python 3.10, 3.11, and 3.12 (see .github/workflows/ci.yml; Python 3.13 is not yet covered by CI):
# Run the full unit test suite
pytest
# Run BioNexus Eval Benchmark across all 8 reliability pillars.
# Strict mode (--strict / BIONEXUS_EVAL_STRICT=1) fails on any L3 case that
# could not verify its planted-truth outcome because a backend was missing.
bionexus eval --strict
# Validate / run BioFailureBench, the scientific trap corpus (BNS-014)
bionexus bench validate
bionexus eval --suite biofailurebench
# Run backend lifecycle matrix tests
pytest tests/unit/test_backend_matrix.py -v
# Run code style & linting checks
ruff check .
-
📜 Changelog & Release Notes: Full record of changes and release highlights.
-
🏛️ Semantic Versioning Policy: Release lifecycle, support windows, and versioning rules.
-
🤖 Compatibility Matrix: AI agent hosts, Python runtimes, and bioinformatics backend versions.
-
🚀 Migration & Upgrade Guide: How to migrate from EvidenceCard 1.0 to EvidenceCard 2.0.
-
⏳ Deprecation Policy & Sunset Schedule: 3-phase deprecation policy and timeline.
-
🛠️ Developer & Skill Development Guide: Anatomy of a Gold Reference skill and CLI scaffolding.
-
🔬 Independent Validation Network: Computed flagship external-validation quotas, calibration freeze on held-out contexts, and honest gap ledger (BNS-023).
-
🤝 Contributing Guidelines: Scientific honesty contract and pull request acceptance criteria.
RESEARCH USE ONLY (RUO):
BioNexus is intended solely for scientific research and educational purposes.
- Not for Clinical Diagnosis: BioNexus is not certified under CLIA, CAP, or IVDR, and its outputs must never be used as the sole basis for clinical diagnostic or treatment decisions.
- Not 21 CFR Part 11 Certified: Provenance tracking features generate standard cryptographic hashes and W3C PROV-O records, but do not constitute an FDA 21 CFR Part 11 compliant electronic signature system.
- AI Output Verification: All computational outputs, evidence grades, and code generated by AI models should be reviewed and validated by qualified scientific personnel.
BioNexus is open-source software licensed under the Apache License, Version 2.0.
Copyright (c) 2026 BioNexus Team.