complexa-target

Ajouter ou modifier une cible de design dans Proteina-Complexa. Les cibles vivent dans trois fichiers YAML, un par pipeline complexa design :

configs/targets/targets_dict.yaml — binder protéique (pipeline par défaut)
configs/targets/ligand_targets_dict.yaml — binder ligand
configs/design_tasks/ame_dict_v2.yaml — AME / scaffolding enzymatique

Le CLI complexa target ne gère que les deux premiers. Les tâches AME utilisent un schéma étendu (mêmes champs de base que les cibles ligand plus contig_atoms pour les sélections d'atomes motif par résidu curées manuellement) et ne peuvent être éditées que directement.

Instructions

complexa target add est un simple wrapper autour de « charger YAML → construire dict → ajouter un bloc » (voir src/proteinfoundation/cli/target_manager.py:add_target_cli et append_target_to_dict). Pour une utilisation agentic, éditez simplement le dict de cibles directement — le schéma est court, les entrées existantes sont d'excellents modèles de copie, et vous évitez 14 flags CLI / l'échappement de SMILES en shell. Utilisez le CLI uniquement si vous voulez explicitement son auto-quoteur YAML ou sa sécurité d'invite de remplacement.

Pour une édition hors ligne, travaillez sur le registre fourni ou une copie de sortie demandée. Quand une copie est demandée, créez son répertoire parent et copiez vers une destination absente. Si la destination existe déjà, inspectez et préservez-la : réutilisez-la si c'est la copie de travail prévue, sinon signalez le conflit de chemin. Ne supprimez pas l'arborescence de sortie pour redémarrer une édition de configuration. Un runtime Complexa installé, un GPU, ou une structure cible ne sont pas requis pour écrire la configuration. Utilisez le schéma de champ ci-dessous, préservez les entrées non liées, et relisez le bloc enregistré. La validation des coordonnées reste en attente en l'absence de structure ; terminez la tâche de configuration sans installer un runtime. Avec les outils Read/Edit, lisez la copie de destination avant de l'éditer ; la lecture du chemin d'entrée original ne satisfait pas l'exigence d'Edit pour le chemin de sortie.

Utilisez le schéma ci-dessous et le registre sélectionné ; la référence CLI n'est nécessaire que pour l'utilisation du CLI. Terminez avec l'entrée enregistrée, son pipeline consommateur, le generation.task_name en aval, et l'état de validation.

Étape	Édition directe de fichier (préférée)	CLI
Regarder les cibles existantes	Lire `configs/targets/{,ligand_}targets_dict.yaml` (ou `configs/design_tasks/ame_dict_v2.yaml` pour AME)	`complexa target list` (protein/ligand uniquement)
Regarder une cible	Lire le dict et grep pour la clé	`complexa target show NAME`
Ajouter une nouvelle cible	Ajouter un bloc YAML (Étape 3a)	`complexa target add ...` (Étape 3b)
Vérifier la configuration	Parser le YAML enregistré et comparer l'entrée modifiée et les clés inchangées	`complexa target show NAME --dict PATH`
Vérifier la résolution du chemin PDB à l'exécution	Requiert le pipeline complet et l'environnement	`complexa validate target CONFIG --target NAME`

Étape 1 : Décider du type de cible

Les cibles vivent dans trois fichiers différents, un par pipeline complexa design. Choisissez le fichier en déterminant quel pipeline l'utilisateur exécutera, puis ajoutez l'entrée à ce fichier. Chaque fichier est consommé par exactement un pipeline.

Intention utilisateur	Pipeline	Fichier dict de cibles	Cette skill ?
Lier une surface protéique (PD-L1, IFNAR2, TNF-α, …) — par défaut	`configs/search_binder_local_pipeline.yaml`	`configs/targets/targets_dict.yaml`	Oui — Étape 2 (protéine)
Lier une poche de petite molécule (FAD, SAM, OQO, …)	`configs/search_ligand_binder_local_pipeline.yaml`	`configs/targets/ligand_targets_dict.yaml`	Oui — Étape 2 (ligand)
AME / scaffolding enzymatique (motif + ligand, noms `M####_<pdb>`)	`configs/search_ame_local_pipeline.yaml`	`configs/design_tasks/ame_dict_v2.yaml`	Partiel — voir « Tâches AME » ci-dessous

Tâches AME (pipeline enzymatique)

Les tâches AME vivent sous motif_target_dict_cfg: avec source, target_filename, ligand, contig_atoms, binder_length, et use_bonds_from_file. La chaîne contig_atoms contient des sélections chaîne/résidu/atome curées. Les entrées existantes illustrent la structure du champ, non les sélections pour un nouveau motif. Si les atomes du motif, la sélection du ligand, ou l'emplacement de la structure manquent, listez les entrées manquantes et écrivez un modèle séparé, explicitement incomplet si utile. Laissez le registre inchangé jusqu'à ce que ces entrées scientifiques soient fourni. Un nom de tâche ou un ID PDB seul ne les détermine pas. Dans le transfert d'entrée manquante, expliquez que l'enregistrement sera une édition directe sous motif_target_dict_cfg une fois les sélections curées fournies ; complexa target add ne peut pas enregistrer les tâches AME. Les entrées complètes sont sélectionnées avec ++generation.task_name=<NAME> et configs/search_ame_local_pipeline.yaml.

Étape 2 : Rassembler les informations requises

Utilisez les valeurs fournies et demandez uniquement les informations requises manquantes. Les champs requis diffèrent pour les définitions protéine, ligand et AME.

Cible protéique

Champ	Question	Exemple	Requis
name	« Nom de la cible (utilisé comme clé dict et `task_name`) ? »	`02_PDL1`, `MyTarget_v1`	oui
source	« Répertoire source sous `$DATA_PATH/target_data/` ? »	`bindcraft_targets`, `custom_targets`	oui (ou `target_path`)
target_filename	« Nom de fichier PDB (sans extension `.pdb`) ? »	`PD-L1`, `IFNAR2`	oui (ou `target_path`)
target_input	« Chaîne + plage de résidus — voir référence pour la grammaire. »	`A1-115`, `A1-50,B1-50`	oui
hotspot_residues	« Résidus hotspot (résidus de contact d'interface) ? »	`["A33", "A95", "A102"]`	optionnel, recommandé
binder_length	« Plage de longueur du binder `[min, max]` ou unique `[length]` ? »	`[80, 150]`, `[100]`	optionnel (défaut `[60, 120]`)
pdb_id	« ID PDB de référence (optionnel, métadonnées uniquement) ? »	`"2lag"`	optionnel

Les sélecteurs hotspot codent chaîne + numéro de résidu, pas l'identité d'acide aminé. Par exemple, Tyr42 (Y42) sur la chaîne B explicitement spécifiée devient B42 ; les sélecteurs chaîne/résidu déjà fournis restent inchangés. Préservez la numérotation de résidu de l'utilisateur. Sans coordonnées, signalez que les identités de résidu et l'appartenance à la structure ne sont pas vérifiées.

Cible ligand — champs protéique ci-dessus (moins `target_input`), plus :

Champ	Question	Exemple	Requis
ligand	« Code de résidu ligand PDB à 3 lettres ? »	`FAD`, `OQO`, `SAM`	oui (présence marque la cible comme ligand)
SMILES	« Chaîne SMILES pour le ligand ? »	`"O=C2C3=Nc1cc(c(...)..."`	recommandé ; clé YAML majuscule
ligand_only	« Générer une poche autour du ligand uniquement (pas d'interface protéine-protéine) ? »	`true` / `false`	optionnel (défaut `true`)
use_bonds_from_file	« Utiliser les informations de liaison du PDB/CIF d'entrée ? »	`true` / `false`	optionnel (défaut `true`)
target_input	non requis pour les cibles ligand	—	non

Vérifiez si la clé proposée existe déjà dans le mapping YAML sélectionné. Préservez une entrée existante sauf si l'utilisateur a demandé la mise à jour de cette entrée.

Copiez un SMILES fourni exactement. La sélection de ligand spécifique à une chaîne appartient à la préparation de la structure d'entrée ; n'inventez pas un champ chain ou target_input protéique pour le représenter dans l'entrée ligand.

Exemples

Étape 3a : Ajouter le bloc YAML directement (préféré)

Ouvrez configs/targets/targets_dict.yaml (ou ligand_targets_dict.yaml pour les cibles ligand), trouvez une entrée existante similaire comme modèle de style, et ajoutez le nouveau bloc sous target_dict_cfg:. Indentation deux espaces, une ligne vierge entre les entrées.

Modèle protéique

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

Règles pour correspondre au style du fichier existant (reflète ce que complexa target add émettrait) :

Quotez les plages chaîne/résidu ("A1-115", "A33") et tout SMILES — les chaînes en style flow se trompent avec : et les crochets sinon.
Utilisez des listes en style flow (["A33", "A95"], [64, 155]) — c'est ce que la sauvegarde sur disque produit.
target_input, source, target_filename sont requis pour la protéine. target_path (chemin absolu) peut remplacer source + target_filename si le PDB se trouve en dehors de $DATA_PATH/target_data/.

Modèle ligand

  41_7BKC_LIGAND:
    source: ligand_targets
    target_filename: 7BKC_ligand_centered
    hotspot_residues: [null]
    binder_length: [100]
    pdb_id: 7BKC
    ligand: 'FAD'
    ligand_only: True
    SMILES: "O=C2C3=Nc1cc(c(cc1N(C3=NC(=O)N2)CC(O)C(O)C(O)COP(=O)(O)OP(=O)(O)OCC6OC(n5cnc4c(ncnc45)N)C(O)C6O)C)C"
    use_bonds_from_file: True

La présence de la clé ligand: bascule la cible en mode ligand — il n'y a pas de flag is_ligand séparé. target_input n'est pas requis pour les ligands.

Après l'enregistrement, passez à l'Étape 4 pour vérifier.

Étape 3b : Alternative CLI (`complexa target add`)

Utilisez le CLI quand vous voulez son quotage automatique chaîne/résidu, l'invite de confirmation de remplacement, ou pour connecter la création de cible à un script non-Python. Préférez le mode non-interactif pour l'utilisation agentic (-i / --editor ouvre un éditeur et bloque).

Flags confirmés (de `src/proteinfoundation/cli/target_cli.py`)

Lisez target_schema.md pour le tableau de flags et les exemples CLI travaillés quand ce chemin est nécessaire. Sélectionnez le dictionnaire visé avec --dict ; --source et --target-filename doivent être explicites quand ils diffèrent des défauts du CLI. L'enregistrement AME reste une édition directe.

Étape 4 : Vérifier

D'abord parser le YAML enregistré avec un parseur YAML disponible et vérifier le mapping sélectionné, les types de champ, les valeurs demandées, et la préservation d'autres entrées. Relisez le bloc résultant. Cela vérifie uniquement l'édition de configuration.

Avec une installation Complexa préparée, les configs de pipeline, l'environnement, et la structure cible, vérifiez additionnellement la résolution de chemin à l'exécution de ce checkout :

# 1. Sélectionner le dictionnaire qui a été réellement édité.
complexa target show 02_PDL1 --dict configs/targets/targets_dict.yaml

# 2. Résoudre le chemin PDB et valider qu'il existe sur disque.
#    Cela traverse les défauts Hydra pour trouver le dict de cible.
complexa validate target configs/search_binder_local_pipeline.yaml --target 02_PDL1

complexa validate target (de src/proteinfoundation/cli/validate.py::validate_target) vérifie :

DATA_PATH est défini et target_data/ existe.
Le nom de cible se résout dans target_dict_cfg.
Soit target_path existe, soit $DATA_PATH/target_data/<source>/<target_filename>.pdb existe.
target_input, hotspot_residues, binder_length sont signalés pour qu'un humain puisse les vérifier.

Pour les cibles ligand, utilisez configs/targets/ligand_targets_dict.yaml pour show et configs/search_ligand_binder_local_pipeline.yaml pour la validation ; --target est la clé de cible, pas un chemin de config. Ce validateur ne vérifie pas les identités de résidu, la chimie ligand, ou les contig_atoms AME ; ne décrivez pas une vérification de chemin comme une validation de coordonnées ou scientifique.

Étape 5 : Émettre l'artefact

Enregistrez l'entrée éditée et l'état de validation à l'emplacement de sortie demandé par l'utilisateur (sinon ./target_<name>/). Pour une édition hors ligne, le bloc YAML enregistré suffit ; aucun artefact généré par CLI n'est requis. Sur une installation préparée, un enregistrement target-show peut aussi être enregistré :

mkdir -p target_02_PDL1
complexa target show 02_PDL1 > target_02_PDL1/target_show.txt

Si une définition autonome est demandée, enregistrez l'entrée réelle sous sa clé de registre dans target_definition.yaml. Le transfert devrait inclure le chemin enregistré, la clé de cible, le pipeline consommateur de l'Étape 1, et ++generation.task_name=<NAME>, ainsi que ce que la validation a réellement exécuté. Pour une demande AME incomplète, signalez le modèle séparé, les entrées manquantes, et l'édition directe de registre nécessaire après l'arrivée de ces entrées.

Configuration matérielle requise

Aucune pour la définition de cible — c'est une édition YAML, pas une étape d'entraînement/inférence. L'impact disque est de quelques KB ajoutés au dict de cibles (plus une sauvegarde .yaml.bak automatique écrite par save_targets_dict).

Pour les runs de design / évaluation en aval qui consomment la cible, reportez-vous à complexa-design et references/hardware.md.

Dépannage

Symptôme	Cause	Correction
`Target PDB file: File not found` de `validate target`	`<source>/<target_filename>.pdb` n'existe pas sous `$DATA_PATH/target_data/`	Confirmez la racine PDB et le répertoire source. Utilisez `--target-path /full/path.pdb` si le fichier se trouve en dehors de `target_data/`.
« Target 'X' already exists! Overwrite? (y/N) »	Collision de nom dans le dict	Choisissez soit un nouveau nom, soit passez `-f / --force` pour remplacer.
Résidu hotspot pas dans PDB	Mauvaise chaîne ou numéro de résidu	Ouvrez le PDB, vérifiez à nouveau les lettres de chaîne (sensible à la casse) et les indices de résidu. Les hotspots utilisent le format `<CHAIN><RESNUM>` — voir référence.
Chaîne non trouvée	`target_input` référence une chaîne qui n'existe pas dans le PDB	Inspectez le PDB avec `grep "^ATOM" target.pdb \\| awk '{print $5}' \\| sort -u`.
Code ligand manquant du PDB	Le code `ligand` à 3 lettres n'apparaît pas comme un nom de résidu `HETATM` dans le fichier	Ouvrez le PDB et vérifiez les lignes `HETATM` ; vous pourriez avoir besoin d'une variante `_ligand_centered` du PDB.
Échec du parsing SMILES en aval	Mauvaise chaîne SMILES	Validez avec `rdkit.Chem.MolFromSmiles(smiles)` avant d'ajouter. Quotez SMILES en shell pour échapper les crochets et parens.
Le nom de cible commençant par un chiffre casse l'interpolation Hydra	YAML traite `02_PDL1` comme une chaîne correctement ; certaines syntaxes de surcharge nécessitent du quotage	Utilisez `++generation.task_name=02_PDL1` ; quotez si le shell supprime des caractères.
`target_input` semble ignoré pour une cible ligand	Par conception — les cibles ligand n'utilisent pas `target_input` ; la poche est définie par le ligand	Laissez-le non défini pour les cibles ligand.

Référence

references/target_schema.md — chaque champ, grammaire de spécification de chaîne, grammaire de nom de tâche AME, trois exemples travaillés.
configs/targets/targets_dict.yaml — entrées protéiques en direct (copiez une connue-bonne comme modèle).
configs/targets/ligand_targets_dict.yaml — entrées ligand en direct.
configs/design_tasks/ame_dict_v2.yaml — définitions de tâche AME (édition directe uniquement, non exposée via CLI complexa target).
src/proteinfoundation/cli/target_cli.py — source de vérité argparse.
src/proteinfoundation/cli/target_manager.py — add_target_cli, list_targets, show_target, schéma dans TARGET_FIELDS.
src/proteinfoundation/cli/validate.py — implémentation de validate_target.