Graduate contacts-v1 inference into the marinfold CLI

[timodonnell]

What

Graduates contacts-v1 inference into the marinfold CLI so the README "Try it out" (and a Colab notebook) can run our current-best model — eric-czech's #61/#75 contacts-v1 1.5B (issue #61, eval loss 2.7566), exported to the open-athena bucket by #89. Previously the graduated contacts_v1 package only did generate/view/tokenizer; inference lived only in the exp82/exp89 eval harnesses.

Supports both contact-prediction readouts, selectable via --method:

• pairwise (default, ~0.3 s/protein) — symmetrized autoregressive P(contact) per pair, optionally averaged over --ensemble-k resampled realizations (exp: evaluate best contacts-v1 model on current eval set #89's TTA).
• rollout (exp82's settled best LM-only recipe, ~50 s/protein) — vote over --n-rollouts sampled contact-section completions, each from a freshly resampled document, tie-broken by the pairwise log-prob (combined = votes + ½·minmax(pairwise sym)).

How

• inference/core.py — adds a sample_completions sampling primitive to the Backend protocol (the existing surface was forward-pass-only).
• inference/_vllm.py + _transformers.py — implement it (vLLM SamplingParams + generate; transformers model.generate). MLX raises NotImplementedError for rollout (pairwise still works there).
• contacts_v1/inference.py — pairwise readout over the existing Backend.next_token_probs; _rollout_score_matrix (resample → vote → pairwise tie-break); _score_matrix dispatches on method. Records are method-agnostic (score + method).
• contacts_v1/{plots,cli}.py — method-aware heatmap labels; infer/evaluate gain --method / --n-rollouts / --temperature / --top-p / --top-k (contacts-v1-specific knobs stay on the per-impl driver; top-level marinfold infer stays pairwise/narrow).
• MODELS.yaml — new 1.5B-contacts-v1 entry, now the default (was 1B).
• README + Colab notebook — "Try it out" headlines the contacts-v1 contact map (pairwise default, rollout via vLLM as the best recipe); notebooks/inference_example1.ipynb repointed to the contacts-v1 model with a pairwise/rollout selector; distogram models kept as "previous generation".

Validation

• 215 unit tests pass (stub-backend, no model download), incl. rollout vote-counting across resampled realizations, the votes + [0,0.5) tie-break bound, and method dispatch.
• End-to-end with the published 5.9 GB checkpoint (transformers; this box's NVIDIA driver predates torch's bundled CUDA, so it runs CPU — correctness unaffected):
  • pairwise evaluate on tests/data/1QYS.cif → long-range AUC 0.957 (exp89 regime).
  • rollout infer on Trp-cage → integer votes + [0,0.5) pairwise tie-break, exactly as designed.
  • Notebook compute cells dry-run against the checkpoint → AUC 0.957 + metrics/PDF/PNG written.

Notes for review

• Default model changed 1B → 1.5B-contacts-v1.
• MODELS.yaml deliberately omits wandb_url for the new entry (I don't have the verified link — it's eric's eric-czech/marin run; drop the exact URL in).
• vLLM sample_completions is unverified on this box (GPU driver too old for the bundled CUDA) — it follows vLLM's standard generate API; the rollout logic is verified via transformers. MLX rollout is a deliberate NotImplementedError (an exp82 follow-up).

🤖 Generated with Claude Code