molclaw-equiscore-docking

name	molclaw-equiscore-docking
description	End-to-end docking-score ranking using EquiScore for candidate molecules against a target protein.
license	MIT license
metadata	{"skill-author":"PJLab"}

1. EquiScore Docking Ranking Skill

Note:

• Local files are not directly accessible by the server. Please upload them to the server using molclaw-file-transfer before execution.
• For PDB file inputs, it is recommended to preprocess them using molclaw-pdbfixer before execution.
• Please refer to skill molclaw-scp-server to complete tool invocation.

step 1. Retrieve target protein structure (skip if user already provides PDB).

• Use skill molclaw-protein-structure-retrieve.

step 2. Optional chain extraction (only if specific chains are required).

response = await client.session.call_tool(
    "extract_and_save_chains",
    arguments={"pdb_file_path": pdb_path, "chain_ids": chain_ids}
)
result = client.parse_result(response)
pdb_path = result["out_file"]

step 3. Fix receptor structure with PDBFixer.

response = await client.session.call_tool(
    "fix_pdb",
    arguments={
        "input_path": pdb_path,
        "add_hydrogens": True,
        "ph": 7.0,
        "remove_heterogens": True,
        "remove_water": True,
        "replace_nonstandard": True
    }
)
result = client.parse_result(response)
fixed_pdb_path = result["output_file"]

2. EquiScore-based Ranking Flow

step 4. Drug-likeness filtering.

• Keep molecules satisfying: QED >= 0.2 and lipinski_rule_of_5_violations <= 2.
• Always compute from returned result["metrics"]; do not use manually copied values.
• Assert len(metrics) == len(candidate_smiles_list) before filtering.

response = await client.session.call_tool(
    "calculate_mol_drug_chemistry",
    arguments={"smiles_list": candidate_smiles_list}
)
result = client.parse_result(response)

metrics = result["metrics"]

filtered_smiles = [
    m["smiles"] for m in metrics
    if m["qed"] >= 0.2 and m["lipinski_rule_of_5_violations"] <= 2
]

step 5. Build EquiScore docking input.

Important:

• EquiScore needs a docking-result SDF (ligand poses relative to receptor).
• Raw SDF converted directly from SMILES is not sufficient for equiscore_pocket.

Two valid modes:

• Mode A: user already provides docking_result_sdf_path -> use directly.

• Mode B: only SMILES provided -> first generate docking poses using the molecule_docking_quickvina_fullprocess tool (which accepts PDB + SMILES directly and handles all format conversions internally), then convert the output docking pose file to SDF and set docking_result_sdf_path to the resulting docked file before continuing to step6. This ensures receptor-relative poses.

When converting formats, use this tool:

response = await client.session.call_tool(
    "convert_smiles_to_format",
    arguments={"inputs": filtered_smiles, "target_format": "sdf"}
)
result = client.parse_result(response)
convert_results = result["convert_results"]

Tool contract:

convert_smiles_to_format(inputs: List[str], target_format: str)
Args:
  inputs: list of SMILES strings or .smi file paths
  target_format: sdf/mol/mol2/pdb/pdbqt/xyz/cif/inchi
Return:
  status, msg, convert_results[{input, output_file}]

step 6. Run EquiScore pocket extraction first.

• Use molclaw-equiscore-tool -> equiscore_pocket.
• Before first call, verify tool argument names from schema (list_tools + inputSchema) if uncertain.

response = await client.session.call_tool(
    "equiscore_pocket",
    arguments={
        "docking_result": docking_result_sdf_path,
        "receptor_pdb": fixed_pdb_path,
        "pocket_cutoff": None,
        "dry_run": False
    }
)
pocket_res = client.parse_result(response)
pocket_dir = pocket_res["pocket_dir"]

If split_sdf_count == 0 or pocket_item_count == 0, fix docking input first and rerun this step.

step 7. Run EquiScore screening.

• Use molclaw-equiscore-tool -> equiscore_screen.

response = await client.session.call_tool(
    "equiscore_screen",
    arguments={
        "pocket_dir": pocket_dir,
        "ngpu": 1,
        "batch_size": 128,
        "num_workers": 8,
        "multi_pose": False,
        "pose_num": 1,
        "debug": False,
        "dry_run": False
    }
)
screen_res = client.parse_result(response)
predictions_path = screen_res["predictions_path"]
score_field = screen_res.get("score_field")

step 8. Rank and return.

• Prefer direct CSV read from predictions_path.
• If direct read fails, use molclaw-file-transfer (server_file_to_base64) to fetch CSV and parse locally.
• Preserve ligand_to_smiles_map; do not assume CSV always has a smiles column.