docs/BIONEMO_SCIENCE_TOOLS.md

# FrontierLab v0.10 · BioNeMo scientific-tool preflight

Status: **OFFLINE SCHEMA/PROVENANCE INTEGRATION ONLY**. No scientific endpoint has been called, no Meta/NVIDIA credits were spent, and no model inference result has been generated by this feature.

## Goal

The hackathon uses Meta research reasoning as its core. NVIDIA BioNeMo is strictly an optional, researcher-authorized scientific computation sidecar, not a replacement for required Meta model usage. Existing public HF CPU Basic Space remains Streamlit with no NIM Docker/GPU installation.

## Official NVIDIA sources

- Toolkit: https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit
- Boltz-2 skill: https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit/tree/main/nim-skills/boltz2-nim
- Boltz-2 request/response API: https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit/blob/main/nim-skills/boltz2-nim/references/api.md
- Scientific validation notes: https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit/blob/main/nim-skills/boltz2-nim/references/validation.md

## Code

`frontierlab/bionemo.py` exposes four registered tools: boltz2-nim is OFFLINE_PREFLIGHT_ONLY; proteinmpnn-nim, rfdiffusion-nim and openfold3-nim remain NOT_CONNECTED. Skills are documentation + tool instructions; listing them does NOT install a model or authorize a hosted API call.

`prepare_boltz2(sequence, source_id=...)` validates a canonical uppercase protein sequence of 8–4096 residues, bounded official sampling/recycle parameters, and generates a standard protein-only Boltz-2 request and a **separate publishable manifest that omits the raw sequence**. The request is never sent to NVIDIA in this version. Output status is always PREPARED_NOT_EXECUTED.

`mode='offline_fixture'` is for entirely synthetic software tests, and cannot carry a review approval. `mode='research'` requires `researcher_authorized=True` and a FrontierLab live literature Run where **all claims have human review and at least two distinct papers are marked human-supported**. This is *authorization for local preflight preparation only*, not approval to transfer a sequence externally.

`validate_boltz2_response(prepared, response)` checks a supplied dictionary against the documented Boltz-2 output shape: requested number of structures, nonempty mmCIF-identified content, and one finite numerical confidence score per structure. It returns structure hashes and confidence scores without inventing missing results. Its status RESPONSE_SHAPE_CHECKED_ORIGIN_UNVERIFIED makes clear that the caller could have supplied a synthetic response. It does not establish that a real hosted request happened, structure predictions are physically correct, scores are pLDDT, binding occurs, or biological activity is confirmed.

## Try the local preflight

```bash
python -m scripts.bionemo_preflight
python -m pytest -q
```

The sample is a clearly declared artificial sequence. The script prints sanitized manifest fields, tool status and SHA-256 hashes only, never credentials, private sequence, or fabricated scientific scores.

## Live inference is deliberately NOT enabled

1. Select a published, safe reference structure/sequence and inspect its license and experimental evidence.
2. Review disclosure: NVIDIA hosted Boltz-2 receives the **entire full protein sequence and request parameters** over HTTPS at https://health.api.nvidia.com/v1/biology/mit/boltz2/predict. Other tools may receive entire PDBs. A private research sequence must never be submitted without explicit data-transfer permission.
3. Confirm NVIDIA entitlement, rate limit, current credits/cost and key scope. No assumptions about unlimited free trial.
4. Add a separate explicit one-shot transport only after authorization, with timeout, no retries, request limits, redacted logs and model-run receipt.
5. Preserve artifacts, controls and runtime metadata, then compare results against independent published reference data. Researcher must review interpretation before publishing.

## Explicit limitations

- Full Boltz-2 API supports DNA/RNA/ligands/MSAs/complexes; this intentionally conservative v0.10 adapter handles protein-only preflight and does not claim to implement the full API.
- NVIDIA response confidence_scores are opaque model confidence estimates. No conversion to pLDDT, measured affinity, in-vitro validation or clinical evidence is justified.
- Test fixtures prove deterministic code behavior only. This feature has **zero experimentally verified model calls**.
- Do not conflate scientific tool output with an independent verdict on the original literature's claim.
- The HF Space needs no restart or upgrade for v0.10 because this adapter is not invoked by its current interface.