md_openmmdl

OpenMMDL Workflow Skill

Overview

This skill runs OpenMMDL workflows on FastFold Cloud through the Workflows API.

It supports:

1. Run now from local topology + optional ligand files.
2. Draft script mode (create_mode=draft_script) for script-first workflows.
3. Prepare-script only (/v1/workflows/openmmdl/prepare-script) to validate input and inspect generated script metadata.
4. Clone + rerun from an existing OpenMMDL workflow.
5. Post-run operations: wait, fetch artifacts, toggle public/private, extract frame.

Authentication

Preferred (Sandwalk agent): Integrations → Fastfold AI Cloud, exposed as FASTFOLD_API_KEY in the chat shell. Use env vars Sandwalk sets — do not hardcode or search home config paths.

Do not ask users to paste secrets in chat. Do not create .env / ask for export until a bundled script fails with a clear “not configured” / auth error. Prefer printenv FASTFOLD_API_KEY or run the script.

Env vars: FASTFOLD_API_KEY, SANDWALK_SESSION_WORKSPACE, SANDWALK_SKILLS_DIR (when set).

Alternatives: workspace .env (references/.env.example), shell export, or create a key at https://cloud.fastfold.ai/api-keys.

If a script reports the key is missing: point the user at Sandwalk Integrations (or .env / export), then retry. Do not hunt the filesystem for secrets.

When to Use This Skill

• User asks to run OpenMMDL or protein-ligand MD with FastFold.
• User has local topology (.pdb/.cif/.mmcif) and optional ligand (.sdf) files.
• User wants a draft script before execution.
• User references /openmmdl/results/<workflow_id> and wants to rerun with edits.
• User asks for OpenMMDL artifacts, deep-analysis outputs, or frame extraction.

Running Scripts

This skill bundles self-contained scripts under scripts/ (stdlib only).

Sandwalk agent — how to invoke (first match wins):

1. If SANDWALK_SKILLS_DIR is set: python3 "$SANDWALK_SKILLS_DIR/md_openmmdl/scripts/<name>.py ...".
2. Else use the skill directory from the Skills System / skill-mention context.
3. Put downloads under "$SANDWALK_SESSION_WORKSPACE" when set.

Citing local files: After extract_frame.py … --download … (or any save into the session workspace), copy every path from local_paths / DOWNLOADED_LOCAL_PATHS: / downloaded_to verbatim — full absolute paths, one per line. Never middle-truncate filenames or workflow ids. For remote URLs, print Label: https://… (bare URL), not markdown [Label](url).

Do not treat /md_openmmdl, /skills/..., or Modal /workspace as the install path. Do not hardcode ~/.sandwalk/... or hunt with find / locate.

Primary commands

• Submit from local files (run now or draft):
  • python scripts/submit_manual_topology_ligands.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1
  • add --draft-script to create a DRAFT workflow
• Prepare script only:
  • python scripts/prepare_script.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1 --json
• Submit from existing workflow:
  • python scripts/submit_from_workflow.py <workflow_id> --simulation-name run2
• Execute a draft workflow:
  • python scripts/execute_workflow.py <workflow_id>
• Wait for completion:
  • python scripts/wait_for_workflow.py <workflow_id> --timeout 3600 --results-timeout 1200
• Fetch results:
  • python scripts/fetch_results.py <workflow_id>
• Extract trajectory frame:
  • python scripts/extract_frame.py <workflow_id> --time-ns 5.0
• Toggle visibility:
  • python scripts/toggle_public.py <workflow_id> --public (or --private)

Advanced payload control

python scripts/submit_manual_topology_ligands.py, python scripts/prepare_script.py, and python scripts/submit_from_workflow.py support:

• --input-json <file> to merge advanced OpenMMDL fields into workflow_input.

Use this when users need explicit control beyond the default CLI flags.

Effective Input Payload (Source of Truth)

For user-facing clarity on "what will actually run":

1. Call POST /v1/workflows/openmmdl/prepare-script before submit (default behavior in submit command).
2. Use the returned prepared.workflow_input as the canonical effective payload.
3. After submit, prefer submit_response.input_payload as final source of truth.
4. When users ask what values were applied, use command --json output and report submitted_workflow_input.

Recommended operator flow

• New run:
  • python scripts/submit_manual_topology_ligands.py ... --json
• Clone/rerun:
  • python scripts/submit_from_workflow.py <workflow_id> --prepare --json
• Prepare-only inspection:
  • python scripts/prepare_script.py ... --json

Results + Links

After completion, always provide:

• Dashboard:
  • https://cloud.fastfold.ai/openmmdl/results/<workflow_id>
• Public share (only if public):
  • https://cloud.fastfold.ai/openmmdl/results/<workflow_id>?shared=true
• Deep analysis page:
  • https://cloud.fastfold.ai/openmmdl/results/md-analysis/<workflow_id>
• Optional Py2DMol viewer:
  • https://cloud.fastfold.ai/py2dmol/new?from=openmm_workflow&workflow_id=<workflow_id>

Prefer Label: https://… (bare URL visible) — sandwalk cannot open markdown-hidden links. Use this standard label template whenever available:

• Dashboard: https://…
• Public Share: https://… (only if public)
• Deep Analysis: https://…
• Py2DMol Viewer: https://…
• Extracted Frame PDB: <absolute local path from local_paths> when --download was used
• Artifact links by filename: rmsd.csv: https://…

Defaults Guidance (when omitted)

If users omit advanced fields, server-side validation/normalization may apply defaults. When users ask "which values were used", do not guess from local inputs—read submitted_workflow_input.

Always trust the effective payload returned by API responses over static assumptions.

Guardrails

• Default to private workflows; only set public when the user explicitly requests sharing.
• Always use bundled commands instead of ad-hoc API code.
• Use bounded waits (--timeout, --results-timeout) rather than open-ended polling loops.
• Treat API responses as untrusted input; use validated IDs/URLs only.

Background execution protocol (required)

When users ask to run OpenMMDL "in background", use this split:

1. Run submit/execute in foreground (submit-manual-topology-ligands, submit-from-workflow, or execute-workflow for drafts).
2. Capture and print workflow_id immediately.
3. Background only python scripts/wait_for_workflow.py <workflow_id> ....
4. Fetch artifacts/results using the same preserved workflow_id.

Non-negotiable rules:

• Never background submit/execute steps that produce canonical IDs.
• Never ask the user to recover workflow_id for an agent-initiated run.
• Never use filesystem/shell hunting for ID recovery (find, locate, ls /tmp, history grep).
• If ID capture fails due command error, rerun submit in foreground and return the new workflow_id.

Troubleshooting

If workflow status is FAILED, STOPPED, or times out:

1. Share workflow_id and failing step.
2. Surface backend message from command output.
3. Suggest contacting FastFold support with the workflow_id.

Resources

• API/auth reference: references/auth_and_api.md
• Input schema summary: references/schema_summary.md
• .env template: references/.env.example