--- name: antibody-design description: Prepare, launch, monitor, and summarize the real RFdiffusion to ProteinMPNN to Protenix antibody pipeline on a local or remote ScienceDiscovery Runner with sandboxed Ascend NPUs. --- # Sandboxed Ascend antibody Protenix pipeline Run the model pipeline as one managed background Shell Execution. Use the same Runner and managed scientific environment for preparation, validation, launch, monitoring, and output transfer. ## Execution contract - Launch model/NPU work only with `run_shell(background=true)` and the bundled `scripts/run_sandbox_pipeline.sh`. Do not use `run_npu_job`, a host bridge, `nohup`, a persistent kernel, or an Agent-authored copy of the bundled scripts. - Select `runner_id` from the Runners authorized for the Session. Do not hardcode `local`. A remote Runner has an independent workspace and independent managed environments. - Retain the returned Shell Execution ID. Monitor it with `execution_status` and `execution_logs`; these calls do not take the workspace write lock. Never submit the pipeline again because a wait ended or an execution is `unknown`. - Model code, checkpoints, input PDBs, and outputs must resolve inside the selected Runner workspace. Put model assets below `antibody_pipeline/models/`. Config paths are workspace-relative. Do not use host absolute paths, symlink escapes, `python`, `scripts_dir`, `pipeline_env`, or `cann_set_env` in `config.json`. - Python packages belong to the selected Runner's managed scientific environment. Install or update them through `environment_*`, never with pip, conda, or an environment activation script inside `run_shell`. - The NPU cards selected for a Runner are exposed inside the sandbox as logical devices `0..N-1`. `npus` uses those sandbox-local IDs, not the host's physical card numbers. If one card is selected, use `"0"`. - There is no default antigen or antibody framework. Require a target PDB, framework PDB, and chain-labelled hotspots such as `[B45,B46,B49]`. - Treat a missing target, framework, or hotspot list as missing user input. Stop and ask for that input; do not infer an epitope, launch a SubAgent, search the web, or choose residues from geometry without an explicit user request. - On first use in a Session, prepare model code and checkpoints inside the selected Runner workspace with the bundled `--prepare-only` entrypoint. It uses pinned official sources, applies the bundled RFdiffusion MindSpore Tensor-to-PDB compatibility patch, downloads the official RFdiffusion, ProteinMPNN, and Protenix checkpoints, verifies their size and SHA-256, and reuses verified files on later runs in the same Session. Do not invent mirror URLs, scan unrelated host paths, or copy assets from another Session. ## 1. Choose and prepare the Runner Use the Runner catalog in the `run_shell` / `environment_list` tool schema and the Session settings. Choose the machine requested by the user, or the single authorized NPU Runner. Keep its ID as `` for every Runner-scoped call. For a remote Runner: 1. Call `sync_remote_workspace(operation="list", runner_id="")`. 2. Push only missing local inputs with `operation="push"`. Model repositories and checkpoints already present in this Session's remote workspace should stay there; do not copy them back and forth. 3. Use remote-workspace paths in `config.json`. Local file tools cannot inspect remote-only files. Before preparation, check the three required user inputs. If one is missing, ask once and stop this run. The first preparation needs outbound access to the official `gitcode.com`, `gitee.com`, `tools.mindspore.cn`, and `af3-dev.tos-cn-beijing.volces.com` domains. The last domain is used by Protenix for its CCD cache. If the Session sandbox network policy does not allow these domains, report the required allowlist change before launching the download. Do not switch the sandbox to unrestricted network access. The user or operator must select usable Ascend cards for that Runner in system settings before launch. The sandbox receives only those cards and renumbers them from zero. ## 2. Select and probe the managed environment Call `environment_list(runner_id="")`. Probe a candidate environment on the same Runner with a short foreground `run_shell` call and keep its environment ID. The environment must provide the packages in `requirements.txt`. Always pass that explicit `environment_id` to the probe; never validate against the Runner's starter/default Python. Probe ready task environments whose names identify this antibody pipeline first (for example, a name containing `antibody`), then probe the remaining ready task environments if needed. After one candidate fails, continue to the next candidate instead of inspecting model source or the uploaded PDBs for a Python dependency problem. Validate that complete, single-source dependency manifest with the selected environment's Python: ```sh python "$SCIENCEDISCOVERY_SKILLS_DIR/antibody-design/scripts/validate_managed_environment.py" \ "$SCIENCEDISCOVERY_SKILLS_DIR/antibody-design/requirements.txt" ``` The validator reads every dependency and exact pin directly from `requirements.txt`; do not maintain a separate partial package list. If no environment passes, create or update one on the same Runner with `environment_create` / `environment_install`, then probe it again. For a remote Runner, push any workspace-local wheel before installing it. ## 3. Prepare workspace models and config Recommended layout on the selected Runner: ```text antibody_pipeline/ config.json inputs/ target_antigen.pdb antibody_framework.pdb models/ mindscience/ MindSPONGE/applications/{rf_diffusion,proteinmpnn,protenix}/ runs/ ``` The default checkpoint locations are: ```text antibody_pipeline/models/mindscience/MindSPONGE/applications/rf_diffusion/models/RFdiffusion_Ab.ckpt antibody_pipeline/models/mindscience/MindSPONGE/applications/protenix/release_data/checkpoint/ms_model_v0.5.0.ckpt ``` Create `antibody_pipeline/config.json` from `references/real_pipeline_config.example.json`. A minimal config is: ```json { "workspace": "antibody_pipeline", "mindscience_root": "antibody_pipeline/models/mindscience", "target_pdb": "antibody_pipeline/inputs/target_antigen.pdb", "framework_pdb": "antibody_pipeline/inputs/antibody_framework.pdb", "hotspots": "[B45,B46,B49]", "num_designs": 1, "run_name": "custom-antigen-protenix", "npus": "0", "workers_per_npu": 1, "protenix_use_msa": false, "protenix_n_sample": 1, "protenix_seeds": "42", "final_step": 160, "diffuser_t": 200, "force": false } ``` Keep the user's original target-PDB chain labels and residue numbers in `hotspots`. Validation rejects hotspot labels that do not exist as CA residues in the uploaded target PDB and reports its available chains before any model is launched. Keep `diffuser_t >= 15`. Reusing a run name with `force=true` deletes that run's existing stage outputs, so require explicit overwrite intent. Run first-use preparation as a managed background Shell Execution on the same Runner and managed environment: ```text run_shell( scriptPath="$SCIENCEDISCOVERY_SKILLS_DIR/antibody-design/scripts/run_sandbox_pipeline.sh", arguments=["--prepare-only", "--config", "antibody_pipeline/config.json"], runner_id="", environment_id="", background=true ) ``` Retain the returned Execution ID and wait with `execution_status` while reading incremental `execution_logs`. Never resubmit preparation because one wait expired. Preparation checks out the pinned MindScience revision, installs the pinned RFdiffusion `sharker` source package, and downloads the official RFdiffusion and Protenix checkpoints to their default locations. Existing MindScience and `sharker` Git checkouts are verified and moved to their detached pins when necessary; the package is copied to RFdiffusion's expected `env/sharker` path. A non-Git source directory is rejected instead of silently reused. Each download uses a `.part` file and becomes visible only after its expected size and SHA-256 match. Existing verified checkpoints are reused. A fresh Session has a fresh Workspace and therefore downloads once again; sharing model assets across Sessions is outside this Skill. After preparation completes with exit code 0, run foreground validation below. If preparation fails, report its Execution ID and the network, Git, disk-space, or checksum error from its log. Do not search unrelated mount points or replace the official URLs. ## 4. Validate and launch once Run a foreground validation on the selected Runner and environment: ```text run_shell( scriptPath="$SCIENCEDISCOVERY_SKILLS_DIR/antibody-design/scripts/run_sandbox_pipeline.sh", arguments=["--validate-only", "--config", "antibody_pipeline/config.json"], runner_id="", environment_id="", wait_ms=30000 ) ``` For the actual run, remove `--validate-only`, use `background=true`, and omit `wait_ms`. The wrapper validates every input before replacing itself with the pipeline process. Retain the returned ``. For a smoke test, use one design, one selected card, `npus="0"`, and one RF worker. For a multi-card run, select the cards on that Runner first and use the corresponding sandbox-local sequence such as `"0,1,2,3"`. ## 5. Monitor the existing execution Use only the management channel while the workspace-owning execution runs: ```text execution_status(execution_id="", wait_ms=30000) execution_logs(execution_id="", cursor=) ``` Continue from the returned `nextCursor`. Status `queued` or `running` means the same command is alive; wait on it again with the positive `wait_ms` shown above. This blocking management wait is designed to repeat for jobs longer than five minutes. The framework also emits a completion notification, but inspect the recorded status after that notice. Terminal handling: - `completed`: require `provenance="committed"` and exit code 0, then inspect `result.createdFiles` and the final logs. - `failed` or `cancelled`: report the Execution ID, failing stage, exit code, and short error log. Do not launch a replacement automatically. - `unknown`: list this Agent's executions with `execution_status()` and inspect logs. Unknown does not authorize replay. If cancellation is needed, call `execution_cancel` and keep checking until terminal. Do not launch a second Shell to poll files during the run: the active execution owns the workspace write lease. Stage changes and counts are already printed to the managed execution log. ## 6. Return outputs After a local execution completes, declare the screening report, summary CSV, and selected result structures from `result.createdFiles` with `declare_artifact`. After a remote execution completes, pull only the outputs the user needs with `sync_remote_workspace(operation="pull", runner_id="", paths=[...])`, verify the transfer result, and then declare those local files as artifacts. Remote files are not artifacts until they are pulled and declared. Success requires equal RFdiffusion, ProteinMPNN, Protenix-input, and Protenix- confidence counts for `num_designs`, plus both files below: ```text antibody_pipeline/runs//05_screening/protenix_screening_report.md antibody_pipeline/runs//05_screening/protenix_screening_summary.csv ``` Zero candidates passing the scientific screen is valid when every pipeline stage and both screening reports completed. A hotspot mapping error is a failed screening run, not zero contacts.