complexa-target

Files (19)

• BENCHMARK.md
• SKILL.md
• evals.json · evals/
• README-excerpts.md · evals/files/campaign_context/
• SNAPSHOT.md · evals/files/campaign_context/
• binder_generate.yaml · evals/files/campaign_context/configs/pipeline/binder/
• search_binder_local_pipeline.yaml · evals/files/campaign_context/configs/
• source_manifest.json · evals/files/campaign_context/
• SNAPSHOT.md · evals/files/project/
• ame_dict_v2.yaml · evals/files/project/configs/design_tasks/
• ligand_binder_generate.yaml · evals/files/project/configs/pipeline/ligand_binder/
• search_ligand_binder_local_pipeline.yaml · evals/files/project/configs/
• ligand_targets_dict.yaml · evals/files/project/configs/targets/
• targets_dict.yaml · evals/files/project/configs/targets/
• source_manifest.json · evals/files/project/
• hardware.md · references/
• target_schema.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# complexa-target

Add or edit a design target in Proteina-Complexa. Targets live in **three YAML files**, one per `complexa design` pipeline:

- `configs/targets/targets_dict.yaml` — protein binder (**default pipeline**)
- `configs/targets/ligand_targets_dict.yaml` — ligand binder
- `configs/design_tasks/ame_dict_v2.yaml` — AME / enzyme scaffolding

The `complexa target` CLI only manages the first two. AME tasks use an extended schema (the same core fields as ligand targets plus `contig_atoms` for hand-curated per-residue motif atom selections) and are file-edit-only.

## Instructions

`complexa target add` is a thin wrapper around "load YAML → build dict → append a block" (see `src/proteinfoundation/cli/target_manager.py:add_target_cli` and `append_target_to_dict`). For agentic use, **just edit the targets dict directly** — the schema is short, the existing entries are great copy templates, and you skip 14 CLI flags / SMILES shell-escaping. Use the CLI only if you explicitly want its YAML auto-quoter or its overwrite-prompt safety.

For an offline edit, work on the supplied registry or requested output copy.
When a copy is requested, create its parent directory and copy into an absent
destination. If the destination already exists, inspect and preserve it: reuse
it when it is the intended working copy, otherwise report the path conflict.
Do not delete the output tree to restart a configuration edit.
An installed Complexa runtime, GPU, or target structure is not required to write
the configuration. Use the field schema below, preserve unrelated entries, and
read back the saved block. Coordinate validation remains pending when the
structure is absent; finish the configuration task without installing a runtime.
With Read/Edit tools, read the destination copy before editing it; reading the
original input path does not satisfy Edit's requirement for the output path.

Use the schema below and the selected registry; the CLI reference is needed
only for CLI use. Finish with the saved entry, its consumer pipeline, the
downstream `generation.task_name`, and the validation status.

| Step | Direct file edit (preferred) | CLI |
|---|---|---|
| Look at existing targets | Read `configs/targets/{,ligand_}targets_dict.yaml` (or `configs/design_tasks/ame_dict_v2.yaml` for AME) | `complexa target list` (protein/ligand only) |
| Look at one target | Read the dict and grep for the key | `complexa target show NAME` |
| Add a new target | Append a YAML block (Step 3a) | `complexa target add ...` (Step 3b) |
| Verify configuration | Parse the saved YAML and compare the changed entry and untouched keys | `complexa target show NAME --dict PATH` |
| Check runtime PDB-path resolution | Requires the full pipeline and environment | `complexa validate target CONFIG --target NAME` |

## Step 1: Decide the target type

Targets live in **three different files**, one per `complexa design` pipeline. Pick the file by working out which pipeline the user will run, then add the entry to that file. Each file is consumed by exactly one pipeline.

| User intent | Pipeline | Targets dict file | This skill? |
|---|---|---|---|
| Bind a protein surface (PD-L1, IFNAR2, TNF-α, …) — **default** | `configs/search_binder_local_pipeline.yaml` | `configs/targets/targets_dict.yaml` | Yes — Step 2 (protein) |
| Bind a small-molecule pocket (FAD, SAM, OQO, …) | `configs/search_ligand_binder_local_pipeline.yaml` | `configs/targets/ligand_targets_dict.yaml` | Yes — Step 2 (ligand) |
| AME / enzyme scaffolding (motif + ligand, `M####_<pdb>` names) | `configs/search_ame_local_pipeline.yaml` | `configs/design_tasks/ame_dict_v2.yaml` | Partial — see "AME tasks" below |

### AME tasks (enzyme pipeline)

AME tasks live under `motif_target_dict_cfg:` with `source`, `target_filename`,
`ligand`, `contig_atoms`, `binder_length`, and `use_bonds_from_file`. The
`contig_atoms` string contains curated chain/residue/atom selections. Existing
entries illustrate the field structure, not the selections for a new motif.
If motif atoms, ligand selection, or structure location are missing, list the
missing inputs and write a separate, explicitly incomplete template if useful.
Leave the registry unchanged until those scientific inputs are supplied. A task
name or PDB ID alone does not determine them. In the missing-input handoff,
explain that registration will be a direct edit under `motif_target_dict_cfg`
once the curated selections are supplied; `complexa target add` cannot register
AME tasks. Completed entries are selected with `++generation.task_name=<NAME>`
and `configs/search_ame_local_pipeline.yaml`.

## Step 2: Gather required info

Use the supplied values and ask only for missing required information. Required
fields differ for protein, ligand, and AME definitions.

### Protein target

| Field | Question | Example | Required |
|---|---|---|---|
| name | "Target name (used as the dict key and `task_name`)?" | `02_PDL1`, `MyTarget_v1` | yes |
| source | "Source directory under `$DATA_PATH/target_data/`?" | `bindcraft_targets`, `custom_targets` | yes (or `target_path`) |
| target_filename | "PDB filename (no `.pdb` extension)?" | `PD-L1`, `IFNAR2` | yes (or `target_path`) |
| target_input | "Chain + residue range — see reference for grammar." | `A1-115`, `A1-50,B1-50` | yes |
| hotspot_residues | "Hotspot residues (interface contact residues)?" | `["A33", "A95", "A102"]` | optional, recommended |
| binder_length | "Binder length range `[min, max]` or single `[length]`?" | `[80, 150]`, `[100]` | optional (default `[60, 120]`) |
| pdb_id | "Reference PDB ID (optional, metadata only)?" | `"2lag"` | optional |

Hotspot selectors encode **chain + residue number**, not amino-acid identity.
For example, Tyr42 (`Y42`) on explicitly specified chain B becomes `B42`;
already supplied chain/residue selectors stay unchanged. Preserve the user's
residue numbering. Without coordinates, report that residue identities and
membership in the structure are unverified.

### Ligand target — protein fields above (minus `target_input`), plus:

| Field | Question | Example | Required |
|---|---|---|---|
| ligand | "3-letter PDB ligand residue code?" | `FAD`, `OQO`, `SAM` | yes (presence marks target as ligand) |
| SMILES | "SMILES string for the ligand?" | `"O=C2C3=Nc1cc(c(...)..."` | recommended; uppercase YAML key |
| ligand_only | "Generate pocket around ligand only (no protein-protein interface)?" | `true` / `false` | optional (default `true`) |
| use_bonds_from_file | "Use bond info from the input PDB/CIF?" | `true` / `false` | optional (default `true`) |
| target_input | not required for ligand targets | — | no |

Check whether the proposed key already exists in the selected YAML mapping.
Preserve an existing entry unless the user requested that entry's update.

Copy a supplied SMILES exactly. Chain-specific ligand selection belongs to
preparation of the input structure; do not invent a `chain` field or protein
`target_input` to represent it in the ligand entry.

## Examples

### Step 3a: Append the YAML block directly (preferred)

Open `configs/targets/targets_dict.yaml` (or `ligand_targets_dict.yaml` for ligand targets), find a similar existing entry as a style template, and append the new block under `target_dict_cfg:`. Two-space indent, single blank line between entries.

#### Protein template

```yaml
  02_PDL1:
    source: bindcraft_targets
    target_filename: PD-L1
    target_input: "A1-115"
    hotspot_residues: ["A37", "A39", "A49", "A98"]
    binder_length: [64, 155]

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills