docs(skills): add structured DPA4 workflow support

doc/agent-skills.md

@@ -18,14 +18,17 @@ in the DeePMD-kit repository under `skills/`.
   The skill uses progressive disclosure: the top-level workflow handles common
   training steps and model selection, while model-specific configuration lives
   under `skills/deepmd-train/models/` and is read only after a model is chosen.
-  Current references include DPA3 and se_e2_a.
+  Current references include DPA3, DPA4/SeZM, and se_e2_a.
 - `deepmd-finetune-dpa3`: Fine-tune DPA3 models from self-trained checkpoints,
   multi-task pretrained models, or built-in models downloaded by `dp pretrained download`.
+- `deepmd-finetune-dpa4`: Fine-tune DPA4/SeZM checkpoints with the PyTorch
+  backend using standard or LoRA fine-tuning, then validate and export to `.pt2`.
 - `deepmd-python-inference`: Run Python and CLI inference with trained or
-  frozen DeePMD-kit models, including energy, force, virial, descriptor, and
-  model-deviation workflows.
+  frozen DeePMD-kit models, including DPA4/SeZM `.pt2` archives and energy,
+  force, virial, descriptor, embedding, and model-deviation workflows.
 - `lammps-deepmd`: Prepare, explain, and run LAMMPS simulations with DeePMD-kit
-  potentials, including common NVE, NVT, and NPT setups.
+  potentials, including DPA4/SeZM `.pt2` deployment and common NVE, NVT, and
+  NPT setups.
 
 ## Related reference
 
@@ -78,5 +81,7 @@ without launching an expensive calculation. For example:
   for loading a frozen DeePMD-kit model and evaluating one frame.”
 - “Use the `deepmd-train` skill to choose between DPA3 and se_e2_a for a small
   water dataset and draft a training input, but do not start training.”
+- “Use the `deepmd-finetune-dpa4` skill to inspect a DPA4 checkpoint and draft
+  a LoRA fine-tuning input, but do not start training.”
 - “Use the `lammps-deepmd` skill to prepare an NVT LAMMPS input file for a
   DeePMD-kit model, and explain each command.”

skills/deepmd-finetune-dpa4/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: deepmd-finetune-dpa4
+description: Fine-tune a DPA4 model in DeePMD-kit. Use for standard or LoRA fine-tuning from a DPA4/SeZM .pt checkpoint, validation and .pt2 export.
+compatibility: Requires deepmd-kit with the PyTorch backend. DPA4/SeZM training is GPU-oriented.
+license: LGPL-3.0-or-later
+metadata:
+  author: SchrodingersCattt
+  version: '1.0'
+  repository: https://github.com/deepmodeling/deepmd-kit
+---
+
+# DeePMD-kit Fine-tuning: DPA4
+
+Fine-tune a DPA4/SeZM checkpoint on downstream DeePMD data. This skill covers
+single-task standard and LoRA fine-tuning. Do not infer the model family from a
+`.pt` suffix or filename: DPA3 and DPA4 checkpoints use the same suffix.
+
+## Route the checkpoint
+
+If the user has not already established the model family, inspect the stored
+configuration:
+
+```bash
+dp --pt show pretrained.pt descriptor fitting-net type-map
+```
+
+Use this skill only when the descriptor/model configuration identifies DPA4 or
+SeZM. If the checkpoint is multi-task, inspect its branches before selecting a
+head:
+
+```bash
+dp --pt show pretrained.pt model-branch descriptor type-map
+```
+
+Do not guess a branch. Use `deepmd-finetune-dpa3` instead when the descriptor is
+DPA3, and stop when the family cannot be established.
+
+## Obtain a pretrained checkpoint
+
+Fine-tuning requires a DPA4/SeZM training checkpoint (`.pt`), not a `.pt2`
+deployment archive. Check whether the installed version provides one:
+
+```bash
+dp pretrained download -h
+```
+
+Use only a listed model or a checkpoint supplied by the user or its publisher.
+Record its source and DeePMD-kit version, then verify its descriptor, branch,
+architecture, and `type_map` before use.
+
+## Before fine-tuning
+
+1. Confirm the checkpoint exists and can be inspected.
+1. Confirm training, validation, and held-out systems, labels, and element type maps.
+1. Split correlated frames by independent system, trajectory, or source family;
+   do not create a nominal held-out set by randomly splitting adjacent frames.
+1. Validate each DeePMD system before training: `natoms` is the number of tokens
+   in `type.raw`, coordinate and force widths are `3 * natoms`, and every used
+   label is finite and frame-aligned.
+1. Start from the exact checkpoint architecture. Introducing new element types,
+   changing architecture, or combining specialized spin/property/multi-task
+   configurations requires separate compatibility validation.
+1. Choose standard fine-tuning or LoRA. Do not assume a built-in DPA4 model name;
+   check `dp pretrained download -h` for the installed version.
+
+## Decide whether to use LoRA
+
+Use standard fine-tuning by default. Use LoRA only for a single-task target when
+parameter-efficient adaptation is wanted and the exact base architecture is
+known. LoRA is enabled by a non-null `model.lora` block in the new input; the
+pretrained checkpoint does not need to contain LoRA. Multi-task LoRA targets are
+unsupported.
+
+Periodic LoRA checkpoints retain adapters and can resume training. Best
+checkpoints may merge the adapters into ordinary DPA4 weights, so absence of
+LoRA metadata does not prove LoRA was never used.
+
+## Standard fine-tuning
+
+The model section in `input.json` must match the checkpoint unless the standard
+pretrained-script mechanism is deliberately used:
+
+```bash
+dp --pt train input.json --finetune pretrained.pt
+```
+
+When fine-tuning a single-task target from a multi-task checkpoint and the
+intent is to preserve a particular pretrained fitting head, pass the branch
+selected above:
+
+```bash
+dp --pt train input.json --finetune pretrained.pt --model-branch SELECTED_BRANCH
+```
+
+If `--model-branch` is omitted, the fitting net may be initialized from the
+`RANDOM` branch instead. A multi-task target uses `finetune_head` in each target
+branch rather than the command-line option.
+
+`--use-pretrain-script` replaces only the target `model.descriptor` and
+`model.fitting_net` from the checkpoint. It does not restore the complete model
+configuration. Inspect and reproduce all other required model-level fields in
+the target input, including `type`, spin settings, bridging method/radii, and
+task-specific options:
+
+```bash
+dp --pt train input.json --finetune pretrained.pt --use-pretrain-script
+```
+
+Inspect the resulting configuration and run a bounded initial segment before a
+long training job. Do not combine model-specific additions with
+`--use-pretrain-script` unless that combination has been validated.
+
+## LoRA fine-tuning
+
+DPA4/SeZM supports LoRA adapters for single-task fine-tuning. Copy the exact base
+architecture into `lora_ft.json`, then add:
+
+```json
+{
+  "model": {
+    "type": "dpa4",
+    "lora": {
+      "rank": 16,
+      "alpha": 16.0
+    }
+  }
+}
+```
+
+Run:
+
+```bash
+dp --pt train lora_ft.json --finetune pretrained.pt
+```
+
+When `pretrained.pt` is multi-task, preserve the selected fitting head:
+
+```bash
+dp --pt train lora_ft.json --finetune pretrained.pt \
+    --model-branch SELECTED_BRANCH
+```
+
+Use the shorter command only for a single-task source checkpoint.
+
+The JSON fragment above is not a complete training input. Adapt the full public
+example at `../../examples/water/dpa4/lora_ft.json`, but copy the exact
+architecture from the source checkpoint before adding `model.lora`. Do not add
+`--use-pretrain-script` unless a targeted test confirms that LoRA is retained.
+
+## Monitor and validate
+
+Monitor `lcurve.out` for non-finite values and train/validation divergence.
+Select a checkpoint using validation data, then follow the
+[complete held-out evaluation](../deepmd-python-inference/references/held-out-evaluation.md)
+with that exact native checkpoint and every held-out system. Export for deployment
+only after the complete evaluation meets the task's declared thresholds.
+
+## Export and test
+
+Before export, read
+`../deepmd-python-inference/references/dpa4-freeze-policy.md` and record the
+selected freeze-time inference environment.
+
+DPA4/SeZM uses the `.pt2` AOTInductor export path rather than the conventional
+PyTorch `.pth` freeze path:
+
+```bash
+dp --pt freeze -c ckpt/model.ckpt.pt -o finetuned_model
+dp test -m finetuned_model.pt2 -s /path/to/test_system -n 30
+```
+
+The freeze command detects DPA4/SeZM and writes `finetuned_model.pt2`. Validate
+the exported archive in the target environment before deployment.
+
+For a multi-task checkpoint, freeze the selected head explicitly:
+
+```bash
+dp --pt freeze -c ckpt/model.ckpt.pt -o finetuned_model --head SELECTED_BRANCH
+```
+
+The resulting `.pt2` contains the selected single head; do not pass a branch
+again when loading that archive.
+
+## Checklist
+
+- [ ] The stored descriptor identifies DPA4/SeZM; the `.pt` suffix was not used as proof.
+- [ ] The checkpoint source, DeePMD-kit revision, architecture, and type map are recorded.
+- [ ] The intended branch is explicit for a multi-task checkpoint.
+- [ ] Training, validation, and held-out systems are independent by source family.
+- [ ] Every admitted system has consistent atom counts, shapes, labels, and type maps.
+- [ ] The input architecture is compatible with the checkpoint.
+- [ ] Standard fine-tuning versus LoRA was selected from the task layout and domain shift.
+- [ ] A resumable LoRA checkpoint is distinguished from a merged best checkpoint.
+- [ ] LoRA uses a complete base configuration and is not silently overwritten.
+- [ ] Complete held-out metrics, sample counts, and reference-label scales are reported.
+- [ ] The selected `.pt` checkpoint was exported to and tested as `.pt2`.
+
+## References
+
+- [DPA4 model and LoRA documentation](https://docs.deepmodeling.com/projects/deepmd/en/latest/model/dpa4.html)
+- [Fine-tuning documentation](https://docs.deepmodeling.com/projects/deepmd/en/latest/train/finetuning.html)
+- [Show model information](https://docs.deepmodeling.com/projects/deepmd/en/latest/model/show-model-info.html)

skills/deepmd-python-inference/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: deepmd-python-inference
-description: Run Python inference with DeePMD-kit models using the DeepPot API. Use when the user wants to load a trained/frozen DeePMD model (.pth or .pb) or a built-in pretrained model (e.g., DPA-3.2-5M) in Python, predict energy/force/virial for atomic configurations, evaluate descriptors, or calculate model deviation between multiple models. Also covers using `dp test` CLI for batch evaluation against labeled data.
-compatibility: Requires deepmd-kit Python package installed. PyTorch backend for .pth models, TensorFlow for .pb models.
+description: Run Python inference with DeePMD-kit models using the DeepPot API. Use when the user wants to load a checkpoint, frozen model (.pb or .pth), DPA4/SeZM AOTInductor deployment archive (.pt2), or built-in pretrained model in Python; predict energy/force/virial; evaluate supported descriptors; calculate model deviation; or use `dp test` against labeled data.
+compatibility: Requires deepmd-kit installed with the backend required by the selected model artifact.
 license: LGPL-3.0-or-later
 metadata:
   author: iProzd
-  version: '1.0'
+  version: '1.1'
   repository: https://github.com/deepmodeling/deepmd-kit
 ---
 
@@ -29,15 +29,20 @@ e, f, v = dp.eval(coord, cell, atype)
 ## Agent Responsibilities
 
 1. Determine the model source:
-   - Frozen model file (`.pth` for PyTorch, `.pb` for TensorFlow)
+   - Frozen model file (`.pth` for conventional PyTorch, `.pb` for TensorFlow, or `.pt2` for DPA4/SeZM)
    - Built-in pretrained model name (e.g., `DPA-3.2-5M`)
-   - Checkpoint file (requires freezing first)
+   - PyTorch checkpoint (`.pt`), whose stored model configuration must be inspected before choosing an inference or export path
+1. Read `references/model-artifacts.md` for `.pt`/`.pt2` models or whenever the artifact route is unclear.
+1. Read `references/held-out-evaluation.md` for complete labeled evaluation used for checkpoint selection or production admission.
 1. Determine the inference task:
    - Single-frame prediction (energy, force, virial)
    - Batch prediction over multiple frames
    - Descriptor evaluation
    - Model deviation calculation
    - CLI-based testing against labeled data
+1. Before using descriptor or embedding hooks, confirm that the selected
+   artifact supports them; a loadable `.pt2` does not necessarily contain the
+   serialized model required by those hooks.
 1. Help the user prepare input arrays in the correct format.
 1. Run inference and report results.
 
@@ -54,6 +59,9 @@ dp = DeepPot("model.pth")
 # From a frozen TensorFlow model
 dp = DeepPot("graph.pb")
 
+# From a frozen DPA4/SeZM model
+dp = DeepPot("model.pt2")
+
 # From a built-in pretrained model (auto-downloads if not cached)
 dp = DeepPot("DPA-3.2-5M")
 ```
@@ -196,6 +204,9 @@ Virial RMSE/Natoms : 2.957e-04 eV
 
 With `-d test_detail`, per-frame predictions are saved to files for further analysis.
 
+The 30-frame commands above are bounded examples, not complete held-out evaluation.
+Use `references/held-out-evaluation.md` when the result admits a model for production.
+
 ## Complete Example: Train, Freeze, and Inference
 
 ```python
@@ -285,7 +296,9 @@ dp pretrained download DPA-3.2-5M --cache-dir ./models
 
 ## Agent Checklist
 
-- [ ] Model file exists and is accessible (`.pth`, `.pb`, or valid pretrained name)
+- [ ] Model file exists and is accessible (`.pb`, `.pth`, `.pt`, `.pt2`, or valid pretrained name)
+- [ ] An ambiguous `.pt` checkpoint was classified from its stored configuration, not its filename
+- [ ] The requested descriptor or embedding operation is supported by the specific artifact, not inferred from its suffix
 - [ ] `coord` array is shaped (nframes, natoms\*3) and in Angstrom
 - [ ] `cell` array is shaped (nframes, 9) or `None` for non-periodic systems
 - [ ] `atype` indices match the model's `type_map` ordering

skills/deepmd-python-inference/references/dpa4-freeze-policy.md

@@ -0,0 +1,24 @@
+# DPA4 freeze-time inference policy
+
+Read this reference before exporting a DPA4 `.pt2`. The generated archive may
+embed inference choices, so do not inherit unknown values of
+`DP_TRITON_INFER`, `DP_TF32_INFER`, or `DP_AMP_INFER` from the shell.
+
+Choose one explicit policy for the target node. A conservative production
+baseline that avoids the slow default while retaining full-precision
+accumulation is:
+
+```bash
+export DP_TRITON_INFER=1
+export DP_TF32_INFER=0
+export DP_AMP_INFER=0
+dp --pt freeze -c model.ckpt.pt -o frozen_model
+```
+
+`DP_TRITON_INFER=2` autotunes for the current hardware and therefore reinforces
+the requirement to freeze and run on the same physical node. Levels 1 and 2 keep
+FP32 accumulation. Level 3, TF32, and AMP change the numerical policy and require
+task-specific accuracy and stability validation before production.
+
+Record all three values, device/runtime identity, input and output hashes, freeze
+command, log, and true exit code with the artifact.