PR7: feat(conformers): isolated nvMolKit worker backend

[SergeiNikolenko]

Summary

This PR introduces an isolated nvMolKit-based conformer worker backend.

Goal: provide a fast conformer path without coupling the main Matcha runtime environment to nvMolKit ABI/toolchain dependencies.

Motivation

In-process nvMolKit integration can make the core runtime environment fragile. This PR adopts a worker-process model:

• main process remains clean,
• worker runs in isolated environment,
• backend selection is explicit and configurable.

What Changed

1) Isolated worker package

• Added matcha-nvmolkit-worker package and worker CLI entrypoint.

2) Setup and compatibility scripts

• Added scripts/setup_nvmolkit_worker.py for environment bootstrap and smoke checks.
• Added scripts/nvmolkit_worker.py compatibility wrapper.

3) Runtime integration

• Added backend switching/autodiscovery in preprocessing:
  • MATCHA_CONFORMER_BACKEND=auto|rdkit|worker
  • MATCHA_CONFORMER_WORKER_CMD
  • MATCHA_CONFORMER_WORKER_TIMEOUT_SEC
  • MATCHA_CONFORMER_WORKER_CHUNK_SIZE

4) Worker contract

• Input: input.sdf + params.json
• Output: output.sdf + meta.json
• auto backend: fallback to RDKit
• worker backend: fail-fast

5) Tests and docs

• Added worker contract and conformer tests.
• Updated README and .gitignore for worker setup/use.

File-Level Scope

• .gitignore
• README.md
• matcha/utils/preprocessing.py
• packages/matcha_nvmolkit_worker/README.md
• packages/matcha_nvmolkit_worker/pyproject.toml
• packages/matcha_nvmolkit_worker/src/matcha_nvmolkit_worker/__init__.py
• packages/matcha_nvmolkit_worker/src/matcha_nvmolkit_worker/cli.py
• scripts/nvmolkit_worker.py
• scripts/setup_nvmolkit_worker.py
• tests/test_conformer_generation_batch.py
• tests/test_conformer_generation_in_memory.py
• tests/test_conformer_worker_contract.py

Quick Validation Command

uv run python scripts/setup_nvmolkit_worker.py

MATCHA_CONFORMER_BACKEND=worker \
uv run matcha \
  -r data/protein.pdb \
  --ligand-dir data/ligands \
  --box-json data/box.json \
  --device cuda:0 \
  --n-samples 10 \
  --scorer gnina \
  --gnina-batch-mode combined \
  -o runs \
  --run-name pr7_worker_check \
  --overwrite

6) Auto-setup on first use

• If MATCHA_CONFORMER_BACKEND=auto|worker and no worker command is configured/found,
  Matcha now performs a one-time automatic bootstrap via:
  uv run python scripts/setup_nvmolkit_worker.py --skip-smoke
• New runtime controls:
  • MATCHA_CONFORMER_AUTO_SETUP_WORKER (default 1)
  • MATCHA_CONFORMER_WORKER_SETUP_TIMEOUT_SEC (default 3600)
• On setup failure in auto, Matcha falls back to RDKit.
• In worker mode, Matcha fails fast with a clear install hint.

Auto-setup Validation Command

rm -rf .venv-nvmolkit-worker
MATCHA_CONFORMER_BACKEND=auto uv run matcha \
  -r data/protein.pdb \
  --ligand-dir data/ligands \
  --box-json data/box.json \
  --device cuda:0 \
  --n-samples 10 \
  --scorer gnina \
  --gnina-batch-mode combined \
  -o runs \
  --run-name pr7_auto_setup_check \
  --overwrite

[SergeiNikolenko]

Superseded by #32 (restacked on #31, no codex/ branch names).