Pymol

PyMOL Headless Rendering

Overview

Two exposed agent tools drive an OSMesa-rendered PyMOL subprocess — no GPU, no X server. Each call writes a PNG image and a .pse session file to disk; the agent only sees {file_path, metadata} in the response, never raw image bytes.

This skill complements VenusFactory's interactive MolstarViewer in the frontend: use Molstar when the user is exploring a structure live, use PyMOL when you need a reproducible static image for a report.

Prerequisites

PyMOL must be on the host's PATH. Verify with pymol -V. If missing, install via:

• conda (preferred): conda install -n venus -c conda-forge pymol-open-source
• pip: pip install pymol-open-source-whl (requires Python 3.10 ≤ x < 3.13)

When PyMOL is missing, the tools return {status: "error", error: {type: "DependencyMissing", message: "<install hint>"}} — surface the install command to the user instead of trying anything else.

Project Tools (VenusFactory2)

Coloring Strategies

When to Use This Skill

• User asks "show me the structure", "render it", "make an image", "compare these two structures"
• Building a report or visualization that needs a static image
• After running an AlphaFold prediction or downloading a PDB, you want to visualize the result
• Comparing predicted vs. experimental structure → superpose_two_structures

When NOT to Use

• User wants to spin / zoom / click on the structure → use the frontend MolstarViewer instead
• Docking / molecular dynamics → out of scope, recommend other tools
• Sequence-only operation → use sequence skills (uniprot, ncbi_sequence_fetch, etc.)
• Animated movies → not exposed; the underlying PyMOL supports it but no agent tool surfaces it

Output Files

Each run produces two files in out_dir:

• *.png — the static image (returned in file_info.file_path).
• *.pse — a PyMOL session file. Tell the user they can open it locally in PyMOL to continue exploring.

Rate / Cost

PyMOL runs locally; no network. Typical render is 5-30 seconds per structure. Default timeout is 5 min — increase timeout_secs for very large complexes or surfaces.

Common Mistakes

• Passing a sequence instead of a structure file → ValidationError: empty pdb_path or NotFound. Download the structure first (e.g., download_alphafold_structure_by_uniprot_id or download_rcsb_structure_by_pdb_id).
• Invalid color_by → ValidationError listing the four allowed values.
• PyMOL not installed → DependencyMissing with the install command. Show the user — don't silently fall back.
• Trying to render very large complexes (>1 M atoms) with surface at high DPI → can time out. Drop dpi to 100 or increase timeout_secs.

References

• references/PYMOL_REFERENCE.md — selection syntax, common commands, gotchas (copied verbatim from google-deepmind/science-skills).
• references/RECIPES.md — 15+ copy-paste PyMOL recipes for advanced visualizations beyond what the two exposed tools cover. Useful when the user wants something custom — produce a one-off script via the lower-level run_pymol_script (in src/tools/visualize/pymol/pymol_runner.py) and run it from the agent's code-execution tool.
• PyMOL open-source homepage / PyMOL wiki