FoldForge sidecar-boltz

Python gRPC sidecar wrapping Boltz (open, MIT-licensed, AlphaFold3-class biomolecular complex structure prediction — proteins + nucleic acids + ligands).

The real model builds a Boltz input YAML (chains with optional precomputed MSA, plus ligands by SMILES/CCD), shells out to boltz predict under the shared cancellable-subprocess runner, parses the ranked CIFs (with confidence/ptm/iptm), and uploads them as content-addressed artifacts.

Contract

Implements BoltzService from FoldForge/proto, vendored here as a git submodule at ./proto. Every sidecar exposes the same shape: a server-streaming Run that emits ProgressEvent heartbeats and ends with a RunResult or ErrorDetail.

Develop (no GPU needed for the gRPC layer)

git clone --recurse-submodules [email protected]:FoldForge/sidecar-boltz.git
cd sidecar-boltz
python3.13 -m venv .venv && source .venv/bin/activate   # Python >= 3.10 required
pip install -e ".[dev]"
./scripts/gen_proto.sh        # generate stubs into src/foldforge_boltz/gen/
pytest -q                     # YAML builder + CIF parser fixtures + gRPC integration

# Start the server. NOTE: there is no __main__ / console-script — invoke serve():
python -c "from foldforge_boltz.server import serve; serve()"   # :50063

Install model deps (GPU box) with pip install -e ".[model]".

Config (env)

var	default	meaning
FOLDFORGE_SIDECAR_BIND	0.0.0.0:50063	gRPC bind address
FOLDFORGE_SIDECAR_WORKERS	4	gRPC thread-pool size
FOLDFORGE_SIDECAR_MOCK	1 (on)	mock model (GPU-free); unset for the real CLI
FOLDFORGE_R2_ENDPOINT	(empty)	object store for artifact upload (empty = compute-only)
FOLDFORGE_R2_BUCKET	foldforge	artifact bucket
FOLDFORGE_GPU_TYPE	A100-80G	advertised GPU type
FOLDFORGE_CANCEL_POLL_INTERVAL_S	1.0	cooperative-cancel poll interval (#M2)
FOLDFORGE_CANCEL_GRACE_PERIOD_S	10.0	SIGTERM→SIGKILL grace on cancel (#M2)

Status

Real-model code is complete; GPU inference is the only gated part.

• Mock mode (FOLDFORGE_SIDECAR_MOCK=1, default) streams realistic ProgressEvents and returns a synthetic content-addressed mmCIF — the full orchestrator → sidecar → object-store path runs with no GPU.
• Real mode (model.py + boltz.py) renders the Boltz YAML, shells out to boltz predict under foldforge_subprocess.run_cancellable (process-group kill on cancel, #M2), parses boltz_results_*/predictions/.../*_model_N.cif + confidence JSON (model 0 = best), and uploads. The inference call needs a GPU + an installed Boltz; _require() raises a clear error when the CLI is absent. See docs/GPU-DEPLOY.md for the GPU runbook.

GPU-free verification (pure YAML builder, CIF parser fixtures, cancel/group-kill, gRPC client-cancel, mock e2e → content-addressed artifacts) all pass via pytest.

License

Apache-2.0