bindsight 0.3.5__py3-none-any.whl

bindsight/design/_common.py

@@ -0,0 +1,501 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Shared designer plumbing: ship the spec+structure to a runner, stage results.
+
+All designer plugins (RFdiffusion+ProteinMPNN, BindCraft, BoltzGen) submit the
+same way — write the ``DesignSpec`` JSON and the target structure into one dir,
+launch the chosen :class:`~bindsight.runners.protocol.GPURunner`, block on
+``fetch``, then stage the tarball and extract ``metrics.jsonl``. The only
+difference is which designer the remote executor dispatches to (recorded in
+``extra_params['designer']``). This module is that shared body.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import tarfile
+from pathlib import Path
+
+from bindsight.design.protocol import DesignResult, DesignSpec
+from bindsight.runners.protocol import GPURunner, JobHandle
+
+LOG = logging.getLogger(__name__)
+
+
+def _code_identity(runner: object) -> str:
+    """Identify the bindsight that will actually execute on the runner.
+
+    A remote runner pip-installs bindsight before running anything, so the code
+    that produces a result is not necessarily the code that submitted it. When
+    the runner carries a working-tree wheel, that wheel's content hash is the
+    exact answer. When it carries only a git ref, the honest answer is the ref
+    name, which is weaker: a branch resolves to different commits over time.
+    With neither, the local package version is the best available.
+
+    Args:
+        runner: the GPU runner about to receive the job.
+
+    Returns:
+        A short string identifying the code, for folding into the cache key.
+    """
+    import hashlib
+
+    wheel = getattr(runner, "bindsight_wheel", None)
+    if wheel is not None:
+        try:
+            digest = hashlib.sha256(Path(wheel).read_bytes()).hexdigest()[:16]
+            return f"wheel:{digest}"
+        except OSError:
+            return f"wheel:{Path(wheel).name}"
+    ref = getattr(runner, "bindsight_ref", None)
+    if ref:
+        return f"ref:{ref}"
+    from bindsight import __version__
+
+    return f"version:{__version__}"
+
+
+def _with_backend(cache_key: str, backend: str, code: str = "") -> str:
+    """Fold the backend, and the code that will run, into a cache key.
+
+    Two runs that differ only in where they executed are not the same work: one
+    may be synthetic. Mixing them is the difference between a real result and a
+    mock's canned numbers wearing a real result's label.
+
+    The same applies to which bindsight runs. A corrected designer benchmark was
+    submitted against a branch whose fixes existed only locally, so the GPU
+    pip-installed the default branch and produced pre-fix output. Had that run
+    succeeded and been cached, a later run of the fixed code would have been
+    handed the unfixed result under the same key.
+
+    Args:
+        cache_key: the spec-derived key.
+        backend: the runner's name.
+        code: identity of the bindsight that will execute, from
+            :func:`_code_identity`. Empty reproduces the previous key exactly,
+            which keeps existing cache entries addressable.
+
+    Returns:
+        The folded key.
+    """
+    import hashlib
+
+    bits = f"{cache_key}|backend={backend}"
+    if code:
+        bits += f"|code={code}"
+    return hashlib.sha256(bits.encode()).hexdigest()
+
+
+def _with_payload(cache_key: str, payload_dir: Path) -> str:
+    """Fold a shipped ``design/`` directory into a cache key.
+
+    The spec-derived key covers what a *designer* would be told to produce. For
+    a ``validate_only`` job nothing is produced: the binders travel in the
+    payload, and the spec is identical no matter which ones. Two calibration
+    sets — twenty scrambles, and the same twenty plus their originals — hashed
+    to the same key against the same target, so the second would have been
+    served the first's twenty rows and read as the answer to a question it never
+    asked. That is the same failure the validator fold in :func:`make_cache_key`
+    exists to prevent, one level further in.
+
+    Both the relative path and the content of every shipped file are covered:
+    renaming a binder changes which row is which downstream. Files are ordered
+    by their POSIX relative path so the key is the same on every platform.
+
+    Args:
+        cache_key: the key so far.
+        payload_dir: the local directory shipped as ``design/``.
+
+    Returns:
+        The folded key.
+    """
+    import hashlib
+
+    digest = hashlib.sha256()
+    # Sorted by the POSIX relative path *string*, not by the Path objects.
+    # `PurePath.__lt__` compares the parts tuple, and case-insensitively on
+    # Windows, so an identical payload hashed in a different order depending on
+    # the operating system: {"a.txt", "a/b.txt", "B.txt"} came out
+    # ["B.txt", "a/b.txt", "a.txt"] on Linux and ["a/b.txt", "a.txt", "B.txt"]
+    # on Windows. The key is meant to be the identity of the content, and an
+    # identity that changes with the machine is not one -- a rerun on CI could
+    # not reuse a local result, and two keys that differed said the payloads did.
+    relative = sorted(
+        (q.relative_to(payload_dir).as_posix(), q) for q in payload_dir.rglob("*") if q.is_file()
+    )
+    for rel, path in relative:
+        digest.update(rel.encode())
+        digest.update(b"\0")
+        digest.update(hashlib.sha256(path.read_bytes()).digest())
+    return hashlib.sha256(f"{cache_key}|payload={digest.hexdigest()}".encode()).hexdigest()
+
+
+def _record_handle(handle_path: Path, handle: object) -> None:
+    """Persist a launched job's handle, without ever failing the job to do it.
+
+    Recording happens *after* the remote job is launched, which makes this the
+    one place where raising would destroy exactly what it exists to protect: the
+    run would abort with a kernel already consuming quota and no record of how
+    to reach it. So every failure here is a warning. A runner whose handle
+    cannot be serialised simply loses reattachability, which is where the tool
+    stood before this existed.
+
+    Args:
+        handle_path: where to write the record.
+        handle: the handle returned by ``runner.submit``.
+    """
+    try:
+        handle_path.parent.mkdir(parents=True, exist_ok=True)
+        dump = getattr(handle, "model_dump_json", None)
+        if dump is None:
+            LOG.warning(
+                "runner returned a %s rather than a JobHandle, so this job cannot "
+                "be reattached to if the client dies",
+                type(handle).__name__,
+            )
+            return
+        handle_path.write_text(dump(indent=2), encoding="utf-8", newline="\n")
+    except (OSError, TypeError, ValueError) as e:
+        LOG.warning(
+            "could not record the job handle at %s (%s); a crashed wait will not "
+            "be able to reattach to this job",
+            handle_path,
+            e,
+        )
+
+
+def _recorded_handle(handle_path: Path, runner: GPURunner) -> JobHandle | None:
+    """Return a still-live job recorded by an earlier client, if there is one.
+
+    A remote job outlives the process that launched it. When the client dies
+    mid-wait — a dropped connection, a closed laptop, a killed terminal — the
+    kernel keeps running and keeps spending a fixed weekly GPU quota, but
+    nothing is left that knows how to collect its output. Resubmitting is the
+    obvious response and the wrong one: it pays for the same work twice and
+    orphans the first job for good. This is the recovery path, and it is why
+    :func:`submit_via_runner` records the handle before it starts waiting.
+
+    A job that ended badly is not reattachable, so its record is cleared and the
+    caller submits afresh. But a job whose state cannot be *determined* is
+    reattached anyway: the cost of waiting on a job that turns out to be dead is
+    one more poll, while the cost of resubmitting a job that is actually alive is
+    hours of quota. :meth:`fetch` retries through transient failures, so the
+    reattached wait recovers on its own once the network does.
+
+    Args:
+        handle_path: where the handle was recorded.
+        runner: the runner to ask about the job's state.
+
+    Returns:
+        The handle to reattach to, or None if the caller should submit.
+    """
+    if not handle_path.is_file():
+        return None
+    try:
+        handle = JobHandle.model_validate_json(handle_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as e:
+        LOG.warning("ignoring unreadable job record %s (%s)", handle_path, e)
+        return None
+    try:
+        state = runner.poll(handle).state
+    except Exception as e:
+        LOG.warning(
+            "could not determine the state of recorded job %s (%s); reattaching "
+            "rather than resubmitting, because a duplicate submission would "
+            "spend GPU quota on work that may already be running.",
+            handle.id,
+            e,
+        )
+        return handle
+    if state in {"queued", "running", "succeeded"}:
+        LOG.info(
+            "reattaching to %s job %s (state=%s) instead of resubmitting",
+            handle.backend,
+            handle.id,
+            state,
+        )
+        return handle
+    LOG.info("recorded job %s ended in state %s; submitting a new one", handle.id, state)
+    handle_path.unlink(missing_ok=True)
+    return None
+
+
+def submit_via_runner(
+    spec: DesignSpec,
+    runner: GPURunner,
+    *,
+    designer_name: str,
+    designer_version: str,
+    designer_commit_sha: str | None,
+    cache_key: str,
+    payload_dir: Path | None = None,
+) -> DesignResult:
+    """Ship spec + structure to ``runner``, block, stage results, return DesignResult.
+
+    ``payload_dir`` is an optional local ``design/`` directory shipped alongside
+    the spec. Validation-only jobs use it to send binders that already exist, so
+    a different validator can be run against them without redesigning.
+    """
+    # The backend belongs in the key. Without it, a run on --backend mock and a
+    # run on a real GPU share a cache entry, so a later real run silently returns
+    # the mock's synthetic tarball and reports it as a genuine result. The
+    # designer's commit is already folded in by the caller; the runner is not.
+    cache_key = _with_backend(cache_key, getattr(runner, "name", "unknown"), _code_identity(runner))
+    payload = Path(payload_dir) if payload_dir is not None else None
+    if payload is not None and payload.is_dir():
+        # Folded here rather than by the caller: this is the function the
+        # payload is handed to, so keying it cannot be forgotten by whoever
+        # ships one next. It must precede spec_dir, which is named after the key.
+        cache_key = _with_payload(cache_key, payload)
+    else:
+        payload = None
+    spec_dir = Path(f"_bindsight_spec_{cache_key[:8]}")
+    spec_dir.mkdir(parents=True, exist_ok=True)
+    if payload is not None:
+        shutil.copytree(payload, spec_dir / "design", dirs_exist_ok=True)
+
+    # Ship the target structure next to the spec (it is not embedded in the
+    # spec). Record the filename in extra_params so the executor can find it.
+    structure_src = Path(spec.target_structure_path)
+    target_name = "target" + (structure_src.suffix or ".pdb")
+    if not structure_src.is_file():
+        # The spec records `target_structure_name` unconditionally, so a missing
+        # structure was not shipped and the spec still told the executor to find
+        # it. `job_exec._locate_structure` raises when it cannot -- but only
+        # after the GPU session has been allocated and paid for, and its own
+        # comment gives the reason to fail early rather than late. The same
+        # argument applies one level further out, where the file is at hand.
+        #
+        # `make_cache_key` makes it worse: a structure it cannot read hashes as
+        # the empty string, so two jobs against two different missing structures
+        # share a key and the second would be served the first's designs.
+        shutil.rmtree(spec_dir, ignore_errors=True)
+        raise FileNotFoundError(
+            f"target structure not found: {structure_src}. The job ships this "
+            "file beside the spec, so it must exist before submitting. Re-run "
+            "the discover stage, or correct target_structure_path."
+        )
+    shutil.copy2(structure_src, spec_dir / target_name)
+    spec_to_send = spec.model_copy(
+        update={"extra_params": {**spec.extra_params, "target_structure_name": target_name}}
+    )
+    spec_path = spec_dir / "spec.json"
+    spec_path.write_text(spec_to_send.model_dump_json(indent=2), encoding="utf-8", newline="\n")
+
+    # Idempotency (ARCHITECTURE.md 4.4): a completed unit of work is identified
+    # by its cache key, so a rerun with identical inputs must not pay for the GPU
+    # again. The key was previously computed and then used only as a directory
+    # name, so every rerun resubmitted. Check it before submitting, and record
+    # the hit or miss so the manifest can show which units were reused.
+    results_dir = Path("./runs/_design") / cache_key
+    staged_archive = results_dir / "results.tar.gz"
+    metrics_path = results_dir / "metrics.jsonl"
+    # A non-empty file is not a readable archive. A download interrupted partway
+    # leaves bytes on disk, and size alone called that a hit -- permanently, on
+    # every rerun, because nothing here ever re-submits once the file exists.
+    # `extract_member` then swallows the TarError as a warning and returns
+    # without writing anything, so the result pointed at a metrics file that was
+    # never created while reporting cache_status="hit". The cache poisoned
+    # itself and stayed poisoned.
+    cache_hit = staged_archive.exists() and staged_archive.stat().st_size > 0
+    if cache_hit and not _archive_is_readable(staged_archive):
+        LOG.warning(
+            "cached archive %s is present but unreadable; treating as a miss and re-running",
+            staged_archive,
+        )
+        cache_hit = False
+    if cache_hit:
+        LOG.info("cache hit for %s; skipping submit (%s)", cache_key[:8], staged_archive)
+        if not metrics_path.exists():
+            extract_member(staged_archive, "metrics.jsonl", metrics_path)
+        if not metrics_path.exists():
+            # A readable archive that does not carry metrics.jsonl is not a
+            # usable result either, and returning its path would hand the caller
+            # a file that is not there.
+            LOG.warning(
+                "cached archive %s carries no metrics.jsonl; treating as a miss", staged_archive
+            )
+            cache_hit = False
+    if cache_hit:
+        shutil.rmtree(spec_dir, ignore_errors=True)
+        return DesignResult(
+            spec=spec,
+            results_archive_path=str(staged_archive),
+            metrics_jsonl_path=str(metrics_path),
+            designer_name=designer_name,
+            designer_version=designer_version,
+            designer_commit_sha=designer_commit_sha,
+            weights_sha256=None,
+            cache_key=cache_key,
+            cache_status="hit",
+        )
+
+    # Record the handle before waiting on it. A remote job outlives its client,
+    # so without this a crashed wait leaves a running kernel that nothing can
+    # collect, and the rerun pays for the same GPU hours again. See
+    # :func:`_recorded_handle`.
+    handle_path = results_dir / "handle.json"
+    try:
+        handle = _recorded_handle(handle_path, runner)
+        if handle is None:
+            handle = runner.submit(spec_path, results_dir=Path("./runs/_design"))
+            _record_handle(handle_path, handle)
+        archive_path = runner.fetch(handle)
+    finally:
+        shutil.rmtree(spec_dir, ignore_errors=True)
+
+    results_dir.mkdir(parents=True, exist_ok=True)
+    if archive_path.resolve() != staged_archive.resolve():
+        shutil.copy2(archive_path, staged_archive)
+    extract_member(staged_archive, "metrics.jsonl", metrics_path)
+
+    return DesignResult(
+        spec=spec,
+        results_archive_path=str(staged_archive),
+        metrics_jsonl_path=str(metrics_path),
+        designer_name=designer_name,
+        designer_version=designer_version,
+        designer_commit_sha=designer_commit_sha,
+        weights_sha256=None,  # multi-GB checkpoints; verified on download
+        cache_key=cache_key,
+        cache_status="miss",
+    )
+
+
+def _archive_is_readable(tar_path: Path) -> bool:
+    """Whether a staged results archive can actually be opened and listed.
+
+    Existence and a non-zero size do not make a tarball readable: an interrupted
+    transfer leaves plausible-looking bytes. Reading the member list is the
+    cheapest check that touches the gzip stream and the tar index, which is
+    where a truncated file fails.
+    """
+    try:
+        with tarfile.open(tar_path, "r:gz", encoding="utf-8") as tf:
+            return bool(tf.getnames())
+    except (tarfile.TarError, OSError, EOFError) as e:
+        LOG.warning("cached archive %s is not readable: %s", tar_path, e)
+        return False
+
+
+def extract_member(tar_path: Path, member: str, dest: Path) -> None:
+    """Extract a single named member from a .tar.gz to ``dest`` (best-effort)."""
+    if not tar_path.exists():
+        return
+    try:
+        with tarfile.open(tar_path, "r:gz", encoding="utf-8") as tf:
+            names = {Path(n).name: n for n in tf.getnames()}
+            if member in names:
+                src = tf.extractfile(names[member])
+                if src is not None:
+                    dest.write_bytes(src.read())
+    except (tarfile.TarError, OSError) as e:
+        LOG.warning("could not extract %s from %s: %s", member, tar_path, e)
+
+
+#: ``extra_params`` entries that change the result, and so belong in the key.
+#:
+#: Deliberately not the whole dict. ``target_structure_name`` is added *after*
+#: the key is computed, so hashing everything would make the key depend on
+#: bookkeeping rather than on the work. These are the entries the remote
+#: executor actually acts on: which validator scores the designs, and whether an
+#: ESM-2 prescreen drops some before they are scored at all.
+#: ``extra_params`` keys that change what a job produces, and so belong in its key.
+#:
+#: ``diffusion_samples`` is here because it changes the reported number, not
+#: just its precision: the validator averages over that many draws, so one draw
+#: and five are different measurements of the same design.
+#:
+#: ``max_parallel_samples`` looks like a performance knob and is not one. The
+#: sampler draws noise shaped by the batch, so the same seed consumes the RNG
+#: stream differently at batch 1 and batch 5 and yields different structures.
+#: Two runs differing only in it are reproducible individually and not
+#: comparable to each other.
+#:
+#: ``mode`` is here because a validate-only job runs no designer at all.
+_RESULT_AFFECTING_PARAMS = (
+    "validator",
+    # ``designer`` selects which designer executes -- ``job_exec`` reads it
+    # straight out of ``extra_params`` -- and was not in this tuple. Two jobs
+    # differing only in it shared a key. That they happened not to collide was
+    # incidental: the three adapters pass distinct pinned commits through
+    # ``extra=``, so the keys differed for a reason unrelated to the field that
+    # chose the tool. ``designer_version`` was absent too, and nothing else
+    # carries it, so bumping a designer's version without bumping its pinned
+    # commit produced an identical key and recorded the new version against the
+    # old cached numbers.
+    #
+    # The docstring below already narrates this exact failure happening once,
+    # for ``validator``.
+    "designer",
+    "designer_version",
+    "prescreen_top_k",
+    "diffusion_samples",
+    "max_parallel_samples",
+    "mode",
+    # Read by ``job_exec`` at the BoltzGen call site and absent from this tuple,
+    # so two BoltzGen jobs differing only in protocol -- a different design task
+    # entirely -- shared a key, and the second silently returned the first's
+    # designs. ``use_kernels`` selects a different compute path for the same
+    # sampler and is not guaranteed bit-identical to the reference one.
+    #
+    # This is the third time an entry the executor acts on was missing from a
+    # hand-kept list; ``tests/test_cache_key_scope.py`` now derives the set the
+    # executor actually reads and fails when one is added without a decision.
+    "boltzgen_protocol",
+    "boltzgen_use_kernels",
+)
+
+#: ``extra_params`` keys the executor reads that deliberately stay out of the key.
+#:
+#: Each needs a reason, because the default for anything the executor acts on is
+#: to be in the key.
+_CACHE_KEY_EXEMPT_PARAMS = {
+    # Assigned after the key is computed, and names the file rather than its
+    # content -- the content is already hashed into the key as ``structure_digest``.
+    # Including it would make the key depend on bookkeeping.
+    "target_structure_name",
+}
+
+
+def make_cache_key(spec: DesignSpec, *, extra: tuple[str, ...] = ()) -> str:
+    """SHA-256 over the deterministic inputs to a design job.
+
+    Covers the target (accession *and* structure content), the epitope, the
+    design ranges, the binder length bounds, the trajectory count, the seed, the
+    result-affecting ``extra_params``, and whatever the caller adds via ``extra``
+    (the designer's pinned commit and resolved parameters). Two jobs sharing a
+    key are the same work.
+
+    The validator belongs here for the same reason the backend does. The remote
+    executor runs whichever validator ``extra_params`` names, so without it a run
+    validated by Boltz-2 and a run validated by Chai-1r shared a cache entry, and
+    the second silently returned the first's numbers under the other validator's
+    name — a wrong answer that looks entirely plausible.
+    """
+    import hashlib
+
+    structure = Path(spec.target_structure_path)
+    structure_digest = ""
+    if structure.is_file():
+        # A new AlphaFold model for the same accession is different work. Without
+        # the content in the key, a rerun would reuse a result computed against
+        # the superseded structure.
+        structure_digest = hashlib.sha256(structure.read_bytes()).hexdigest()
+    bits = "|".join(
+        [
+            spec.target_uniprot,
+            structure_digest,
+            spec.epitope_chain,
+            ",".join(str(r) for r in sorted(spec.epitope_residues)),
+            ",".join(f"{lo}-{hi}" for lo, hi in spec.design_ranges),
+            str(spec.binder_length_min),
+            str(spec.binder_length_max),
+            str(spec.n_trajectories),
+            str(spec.seed),
+            *(f"{k}={spec.extra_params.get(k)}" for k in _RESULT_AFFECTING_PARAMS),
+            *extra,
+        ]
+    )
+    return hashlib.sha256(bits.encode()).hexdigest()

bindsight/design/bindcraft.py

@@ -0,0 +1,78 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""BindCraft designer plugin (premium GPU path).
+
+BindCraft (`Pacesa et al., Nature 2025 <https://www.nature.com/articles/s41586-025-09429-6>`_,
+MIT) is a one-shot AF2-based binder design pipeline with reported ~10-100%
+experimental success rates. Trade-off vs. RFdiff+MPNN: needs ≥32 GB VRAM, so
+free Colab T4 (16 GB) doesn't fit; you need Colab Pro+ A100 or paid Modal.
+
+The GPU work runs in :mod:`bindsight.runners.job_exec`; this module owns the
+plugin entry point and the spec it builds.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from bindsight.design._common import make_cache_key, submit_via_runner
+from bindsight.design.protocol import DesignResult, DesignSpec
+from bindsight.runners.protocol import GPURunner
+from bindsight.runners.tools import BINDCRAFT_COMMIT
+
+LOG = logging.getLogger(__name__)
+
+
+class BindCraftDesigner:
+    """Plugin: BindCraft one-shot binder design (≥32 GB VRAM)."""
+
+    name = "bindcraft"
+    # The adapter's own version, not the upstream tool's. Pinned upstream
+    # revisions live in the spec's extra_params and in the cache key; this
+    # number moves only when this adapter's behaviour does.
+    version = "0.1.0"
+    license_notice = "BindCraft: MIT. Commercial-OK. Requires ≥32 GB VRAM."
+
+    def make_spec(
+        self,
+        *,
+        target_uniprot: str,
+        target_structure_path: Path,
+        epitope_residues: list[int],
+        epitope_chain: str = "A",
+        design_ranges: list[tuple[int, int]] | None = None,
+        n_trajectories: int = 50,
+        seed: int = 0,
+        binder_length_min: int = 50,
+        binder_length_max: int = 100,
+    ) -> DesignSpec:
+        """Build a DesignSpec carrying the BindCraft parameters."""
+        return DesignSpec(
+            target_uniprot=target_uniprot,
+            target_structure_path=str(target_structure_path),
+            epitope_chain=epitope_chain,
+            epitope_residues=epitope_residues,
+            design_ranges=list(design_ranges or []),
+            n_trajectories=n_trajectories,
+            seed=seed,
+            binder_length_min=binder_length_min,
+            binder_length_max=binder_length_max,
+            extra_params={
+                "designer": self.name,
+                "designer_version": self.version,
+                "bindcraft_commit": BINDCRAFT_COMMIT,
+            },
+        )
+
+    def submit(self, spec: DesignSpec, runner: GPURunner) -> DesignResult:
+        """Ship the spec+structure to the runner and stage the results."""
+        cache_key = make_cache_key(spec, extra=(BINDCRAFT_COMMIT,))
+        return submit_via_runner(
+            spec,
+            runner,
+            designer_name=self.name,
+            designer_version=self.version,
+            designer_commit_sha=BINDCRAFT_COMMIT,
+            cache_key=cache_key,
+        )

bindsight/design/boltzgen.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""BoltzGen designer plugin (newest, watch-list for v0.2 default).
+
+`BoltzGen <https://github.com/HannesStark/boltzgen>`_ (Nov 2025, MIT for both
+code and weights) is a "universal binder design" framework from the same
+author as Boltz-2. Permissive license + same family as our default validator
+makes it the strongest v0.2 candidate to replace RFdiff+MPNN as the default
+designer once benchmarked.
+
+The GPU work runs in :mod:`bindsight.runners.job_exec`; this module owns the
+plugin entry point and the spec it builds.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from bindsight.design._common import make_cache_key, submit_via_runner
+from bindsight.design.protocol import DesignResult, DesignSpec
+from bindsight.runners.protocol import GPURunner
+from bindsight.runners.tools import BOLTZGEN_COMMIT
+
+LOG = logging.getLogger(__name__)
+
+
+class BoltzGenDesigner:
+    """Plugin: BoltzGen universal binder design."""
+
+    name = "boltzgen"
+    # The adapter's own version, not the upstream tool's. Pinned upstream
+    # revisions live in the spec's extra_params and in the cache key; this
+    # number moves only when this adapter's behaviour does.
+    version = "0.1.0"
+    license_notice = "BoltzGen: MIT (code + weights). Commercial-OK."
+
+    def make_spec(
+        self,
+        *,
+        target_uniprot: str,
+        target_structure_path: Path,
+        epitope_residues: list[int],
+        epitope_chain: str = "A",
+        design_ranges: list[tuple[int, int]] | None = None,
+        n_trajectories: int = 50,
+        seed: int = 0,
+        binder_length_min: int = 50,
+        binder_length_max: int = 100,
+    ) -> DesignSpec:
+        """Build a DesignSpec carrying the BoltzGen parameters."""
+        return DesignSpec(
+            target_uniprot=target_uniprot,
+            target_structure_path=str(target_structure_path),
+            epitope_chain=epitope_chain,
+            epitope_residues=epitope_residues,
+            design_ranges=list(design_ranges or []),
+            n_trajectories=n_trajectories,
+            seed=seed,
+            binder_length_min=binder_length_min,
+            binder_length_max=binder_length_max,
+            extra_params={
+                "designer": self.name,
+                "designer_version": self.version,
+                "boltzgen_commit": BOLTZGEN_COMMIT,
+            },
+        )
+
+    def submit(self, spec: DesignSpec, runner: GPURunner) -> DesignResult:
+        """Ship the spec+structure to the runner and stage the results."""
+        cache_key = make_cache_key(spec, extra=(BOLTZGEN_COMMIT,))
+        return submit_via_runner(
+            spec,
+            runner,
+            designer_name=self.name,
+            designer_version=self.version,
+            designer_commit_sha=BOLTZGEN_COMMIT,
+            cache_key=cache_key,
+        )