Relative binding free-energy and activity-label prediction workflows using PBCNet 2.0 on SciMiner, with Gnina docking and PDB/database retrieval to complete...

SKILL.md

---
name: FEP-alternative
description: Relative binding free-energy and activity-label prediction workflows using PBCNet 2.0 on SciMiner, with Gnina docking and PDB/database retrieval to complete missing inputs.
credential_files:
- ~/.config/sciminer/credentials.json
---

# FEP Alternative Skill

This skill predicts relative binding free energy or activity labels for newly
designed small molecules using the SciMiner `PBCNet 2.0` tool. It is a
PBCNet-based alternative workflow for FEP-style lead optimization tasks, not an
explicit molecular-dynamics FEP simulation.

The core SciMiner workflow uses:

- `PBCNet 2.0` for relative binding affinity or activity-label prediction
- `Gnina` for generating docked 3D binding conformations when candidate or
reference ligand poses are missing
- PDB database retrieval through the bundled `rcsb-pdb-skill` when the user
has activity data but no protein-ligand crystal structure

## When to use this skill

- Predict relative binding free energy, binding affinity, or activity labels
for newly designed molecules against a known target.
- The user has one or more reference molecules with measured biological
activity against the same target and wants to predict newly designed
molecules.
- The user provides a receptor PDB file, reference ligand conformations, labels,
and candidate molecules, or asks the agent to complete missing receptor,
pocket, docking, or conformation files.
- The user asks for an FEP alternative, fast relative activity prediction,
PBCNet, or PBCNet 2.0.

## Required PBCNet inputs

`PBCNet 2.0` requires these conceptual inputs:

- protein receptor PDB file
- SDF file containing 3D binding conformations of reference molecules
- activity label values for the reference molecules
- SDF file containing docked 3D binding conformations of molecules to be tested

If the user cannot provide all of these files, collect the missing information
and supplement it through the workflows below. Do not send random or undocked
candidate conformations to PBCNet; the candidate SDF must contain already-docked
binding poses.

## Method selection rule

- If all PBCNet-ready files are available, invoke `PBCNet 2.0` directly.
- If a protein-ligand crystal structure or receptor PDB plus original/reference
ligand pose is available, use the original ligand position as the binding
pocket, run `Gnina` to dock the molecules to be tested, and then invoke
`PBCNet 2.0` with the top 3 poses of each ligand ranked by centroid
deviation from the reference pose.
- If measured reference activities are available but no crystal structure is
available, search the PDB for structures of the same target with co-crystal
ligands similar to the measured reference ligands. Keep candidates with
ligand similarity higher than 30%, select the crystal with the highest
ligand similarity and acceptable structure quality, extract the receptor and
binding pocket from that crystal, establish reference poses for measured
molecules, dock test molecules with `Gnina`, rank predicted poses by centroid
deviation from the reference pose, keep the top 3 poses of each ligand for
bioactivity prediction, and then invoke `PBCNet 2.0`.
- If target identity, reference ligand structures, activity labels, or test
molecule structures are missing and cannot be recovered from explicit user
context, ask the user for the missing information before invoking SciMiner.

## Prerequisites

1. Obtain a free SciMiner API key from `https://sciminer.tech/utility`.
2. Store it outside this repository at `~/.config/sciminer/credentials.json`
with JSON shaped as `{"api_key":"your_api_key_here"}`.
3. For SciMiner calls, read the API key from
`~/.config/sciminer/credentials.json` and send it as the `X-Auth-Token`
header.
4. Never print, persist, or store the API key in prompts, logs, or repository
files. Agents should remember only the credential file path.

If `~/.config/sciminer/credentials.json` is not available or does not contain
an `api_key` field, stop and tell the user to obtain a free SciMiner API key
from `https://sciminer.tech/utility` and store it in that file. Do not try to
complete the task by switching to other tools or services.

## Authoritative tool-doc source (required)

The published Markdown files under `https://sciminer.tech/tool_api_files/` are
the single source of truth for SciMiner `provider_name`, `tool_name`, allowed
`parameters`, file-upload behavior, request encoding, and submission flow.

Use these SciMiner Markdown docs:

- `PBCNet 2.0` -> `PBCNet 2.0_api_doc.md`
- `Gnina` -> `Gnina_api_doc.md`

For PDB database retrieval and ligand-similarity searches, read the bundled
database sub-skill before querying public resources:

- `rcsb-pdb-skill/SKILL.md`

The agent MUST:

1. Resolve the selected SciMiner tool's Markdown file and read it before every
invocation.
2. Never invent `provider_name`, `tool_name`, parameter names, enum values,
upload-field names, content type, or submission flow from memory.
3. Extract and follow the selected SciMiner doc section's exact:
- Base URL
- API endpoint
- Content-Type
- Authentication header
- Tool Name
- Method
- Parameter table, including required fields and enum values
- File-upload instructions and example code
4. Choose the correct doc section if the selected doc contains multiple tool
variants, such as reference-ligand input vs pocket-center input.
5. Cite the selected Markdown docs as the payload source in summaries.

If a user-provided parameter is not present in the selected Markdown doc
section, ask for correction or drop it with an explanation.

## Required workflow

1. Build an input ledger before running tools. Track target identity, receptor
PDB or PDB ID, reference molecule structures, reference activity labels and
units, candidate molecule structures, binding pocket definition, and which
files are already PBCNet-ready.
2. Determine whether the task fits the direct PBCNet path, the crystal-guided
docking completion path, or the no-crystal PDB-retrieval path.
3. Read the `PBCNet 2.0` Markdown doc before constructing any PBCNet payload.
4. If docking is needed, read the `Gnina` Markdown doc before docking any
molecule and choose the doc section that matches the available pocket input.
5. If no crystal structure is available, read the bundled
`rcsb-pdb-skill/SKILL.md` sub-skill and retrieve PDB structures for the
same target using ligand similarity to the measured reference ligands. Keep
structures with ligand similarity higher than 30%, prefer the highest
similarity, and consider resolution, chain completeness, ligand relevance,
and mutation state when breaking ties.
6. For crystal-guided workflows, use the original ligand position in the
user-provided or selected crystal structure as the binding pocket.
7. Establish measured reference poses before docking test molecules. If there
is only one measured reference molecule with a matching PDB co-crystal
ligand, use that native ligand pose from the PDB as the reference pose. If
there are multiple measured reference molecules represented across several
PDB files, perform cross-docking among the candidate receptor structures and
measured reference molecules; select the receptor that best preserves native
or mutually consistent reference binding modes, then determine each measured
molecule's reference pose in that selected receptor frame.
8. For no-crystal workflows, extract the protein receptor PDB file and bound
ligand pocket from the selected PDB crystal. When extracting any ligand from
a PDB file, validate and preserve chemical bond orders before writing SDF;
do not allow conversion tools to turn all bonds into single bonds.
9. After extraction and reference-pose determination, dock molecules to be
tested in that pocket.
10. When multiple docked poses are produced, calculate the centroid of each
predicted ligand pose and the centroid of the matched reference pose in the
same receptor coordinate frame. Compute centroid deviation as the Euclidean
distance between those centroids, rank poses for each ligand from smallest
to largest centroid deviation, and keep the top 3 poses of each ligand for
PBCNet bioactivity prediction. If fewer than 3 poses are available for a
ligand, keep all available poses and report the count. Preserve ligand IDs,
pose ranks, and centroid-deviation values in the prepared SDF or companion
metadata when possible.
11. Assemble the reference SDF so its molecule order matches the activity label
order exactly. Preserve user-provided activity units and transformations;
do not invent or convert labels unless the user requested the conversion or
confirmed the rule.
12. Upload required file inputs exactly as described by the selected SciMiner
Markdown docs and replace local paths with returned `file_id` values.
13. Write or run invocation code directly from the selected Markdown docs'
base-information block, parameter table, file-upload instructions, and
example code. Do not apply a shared invocation template or local registry
abstraction in this skill.
14. Poll the task result and return the `share_url` in the final user-facing
summary.

## Missing-input completion rules

- Missing receptor PDB but target and measured ligand are known: search PDB for
same-target co-crystal structures using ligand similarity, require ligand
similarity higher than 30%, then select the best supported crystal.
- Missing candidate binding conformations: run `Gnina` docking in the selected
or user-provided pocket, calculate centroid deviation from the reference pose
for every predicted pose, and use the top 3 poses of each ligand as the
PBCNet candidate conformation input.
- Missing reference ligand SDF but a crystal ligand is present: extract or
prepare the crystal ligand pose as a 3D SDF when that ligand corresponds to a
measured reference molecule. Validate ligand chemistry during extraction:
preserve bond orders from CCD or another trusted chemical template, repair
aromatic/double/triple bonds when needed, and reject or flag outputs where all
bonds have become single bonds. Otherwise ask the user to confirm the
reference mapping.
- Multiple measured reference molecules across several PDB files: perform
cross-docking to select the receptor structure and assign each measured
molecule's reference pose before ranking test-molecule poses by centroid
deviation.
- Missing measured activity labels: ask the user for values and units. Public
database activities may be used only when the user asks for retrieval or
confirms the selected measurements.
- Missing test molecules: ask for SDF, SMILES, or another structure file format
accepted by the selected `Gnina` doc section.

## File upload rules

- Upload every required file parameter described by the selected SciMiner
Markdown doc before invocation.
- Replace local paths in `parameters` with the returned `file_id` strings.
- Use the upload form field documented by the selected SciMiner Markdown doc.
- Skip optional file parameters that the user did not provide.

## Expected result format

```json
{
"status": "SUCCESS",
"result": {...},
"task_id": "xxx",
"share_url": "https://sciminer.tech/share?id=<task_id>&type=API_TOOL"
}
```

## Workflow guidance

- Complete receptor, reference SDF, labels, and docked candidate SDF ->
`PBCNet 2.0`.
- Receptor or crystal structure plus candidate molecules but no candidate poses
-> `Gnina`, centroid-deviation ranking, top 3 poses per ligand, then
`PBCNet 2.0`.
- Reference activities but no crystal structure -> PDB ligand-similarity
retrieval, native-pose or cross-docking reference-pose assignment, receptor
and pocket extraction with ligand bond-order validation, `Gnina` docking,
centroid-deviation ranking, top 3 poses per ligand, then `PBCNet 2.0`.
- Ambiguous labels, units, molecule ordering, target identity, or reference
mapping -> ask for clarification before submitting PBCNet.

## Notes

- Use the selected SciMiner Markdown docs under
`https://sciminer.tech/tool_api_files/` as the authoritative source for
payload construction and invoke-method details.
- Read the SciMiner API key from `~/.config/sciminer/credentials.json` and send
it as the `X-Auth-Token` header. Do not print or persist the API key in
prompts, logs, or repository files.
- If `~/.config/sciminer/credentials.json` is missing or does not contain an
`api_key` field, stop and tell the user to obtain a free SciMiner API key
from `https://sciminer.tech/utility` and store it in that file.
- `provider_name` and `tool_name` must exactly match the selected Markdown doc.
- Use the selected Markdown doc to determine PBCNet `label_list` formatting,
Gnina pocket specification, file inputs, parameter placement, and any
tool-specific submission details.
- Important: when summarizing results to users, attach the `share_url` links of
every successful task at the end so that users can view the online results,
rather than showing file download links.
- For long-running tasks without a fixed ETA, poll for no more than 6000
seconds; if the task is still running, stop polling and return the current
`task_id` and `share_url` so the user can check later.

FEP Alternative

SKILL.md

related skills