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 <runner-id> for every Runner-scoped call.

For a remote Runner:

1. Call sync_remote_workspace(operation="list", runner_id="<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="<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:

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:

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:

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:

{
  "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:

run_shell(
  scriptPath="$SCIENCEDISCOVERY_SKILLS_DIR/antibody-design/scripts/run_sandbox_pipeline.sh",
  arguments=["--prepare-only", "--config", "antibody_pipeline/config.json"],
  runner_id="<runner-id>",
  environment_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:

run_shell(
  scriptPath="$SCIENCEDISCOVERY_SKILLS_DIR/antibody-design/scripts/run_sandbox_pipeline.sh",
  arguments=["--validate-only", "--config", "antibody_pipeline/config.json"],
  runner_id="<runner-id>",
  environment_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 <execution-id>.

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:

execution_status(execution_id="<execution-id>", wait_ms=30000)
execution_logs(execution_id="<execution-id>", cursor=<nextCursor>)

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="<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:

antibody_pipeline/runs/<run_name>/05_screening/protenix_screening_report.md
antibody_pipeline/runs/<run_name>/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.