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,152 @@
+---
+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.
+
+## Before fine-tuning
+
+1. Confirm the checkpoint exists and can be inspected.
+1. Confirm training and validation systems, labels, and element type maps.
+1. Keep a held-out test set that is not used for training or model selection.
+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.
+
+## 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.
+
+If the architecture is unknown, `--use-pretrain-script` can inherit the stored
+model configuration except for `type_map`:
+
+```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
+```
+
+The JSON fragment above is not a complete training input. Adapt the full public
+example at `../../examples/water/dpa4/lora_ft.json`. Do not add
+`--use-pretrain-script` to this LoRA command unless a targeted test confirms that
+the intended LoRA configuration is retained.
+
+## Monitor and validate
+
+Monitor `lcurve.out` for non-finite values and train/validation divergence.
+Select a checkpoint using validation data, then evaluate the selected checkpoint
+on the complete held-out test systems. Report energy and force errors, plus
+virial errors when those labels are part of the task.
+
+## Export and test
+
+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 intended branch is explicit for a multi-task checkpoint.
+- [ ] Training, validation, and held-out test systems are separate.
+- [ ] The input architecture is compatible with the checkpoint.
+- [ ] LoRA uses a complete base configuration and is not silently overwritten.
+- [ ] Training and held-out metrics are finite and reported with units.
+- [ ] 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,19 @@ 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. 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 +58,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")
 ```
@@ -285,7 +292,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/model-artifacts.md

@@ -0,0 +1,93 @@
+# DeePMD model artifacts for inference
+
+Read this reference when the model is a training checkpoint, its extension is
+`.pt2`, or the correct backend/export path is unclear.
+
+## Identify the artifact
+
+A suffix identifies a serialization/backend route, not necessarily a model
+family. In particular, both DPA3 and DPA4 training checkpoints use `.pt`. Never
+classify a `.pt` checkpoint from its filename alone. Inspect its stored model
+configuration when needed:
+
+```bash
+dp --pt show model.pt descriptor fitting-net type-map
+```
+
+| Artifact | Typical role                      | Inference guidance                                                                                                                                |
+| -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.pb`    | TensorFlow frozen model           | Load with `DeepPot` or use `dp test`.                                                                                                             |
+| `.pth`   | Conventional PyTorch frozen model | Load with `DeepPot` or use `dp test`.                                                                                                             |
+| `.pt`    | PyTorch training checkpoint       | Inspect before use. DPA4 supports eager Python evaluation and embedding extraction from a checkpoint; deployment normally uses a frozen artifact. |
+| `.pt2`   | AOTInductor deployment archive    | Use supported inference paths in a compatible runtime; the suffix alone does not imply descriptor hooks, portability, or multi-rank support.      |
+
+Backend selection for inference is normally determined from the model artifact.
+Do not add a backend flag merely from the assumed model family.
+
+## DPA4/SeZM
+
+DPA4/SeZM supports Python evaluation from its `.pt` checkpoint, but a `.pt2`
+archive is the normal frozen deployment artifact. Freeze with:
+
+```bash
+dp --pt freeze -c model.ckpt.pt -o frozen_model
+```
+
+The command writes `frozen_model.pt2` for a detected DPA4/SeZM checkpoint.
+For a multi-task checkpoint, select the head during export with
+`--head SELECTED_BRANCH`; the resulting `.pt2` is already single-head.
+Evaluate the archive with:
+
+```python
+from deepmd.infer import DeepPot
+
+model = DeepPot("frozen_model.pt2")
+energy, force, virial = model.eval(coord, cell, atype)
+```
+
+For labeled data:
+
+```bash
+dp test -m frozen_model.pt2 -s /path/to/system -n 30
+```
+
+`DeepPot.eval` on DPA4/SeZM `.pt2` archives is covered for energy, force,
+virial, atomic energy, and atomic virial. `dp test` uses the same model dispatch.
+Both require an installed DeePMD-kit/PyTorch runtime compatible with the
+compiled archive.
+
+Check that `atype` follows the model `type_map` and that coordinates/cells use
+the units and shapes documented by `DeepPot`.
+
+## Descriptors and DPA4 embeddings
+
+Descriptor evaluation is conditional for `.pt2`. It requires an archive that
+contains the serialized `model.json`; metadata-only archives can run the main
+`DeepPot.eval` path but raise `NotImplementedError` for `eval_descriptor`.
+In particular, do not run `dp eval-desc` on a DPA4 `.pt2` produced by the
+`dp --pt freeze` command above, because that export is metadata-only. Use a
+supported checkpoint or verify the archive contents and backend first.
+
+DPA4 additionally exposes model embeddings from a training checkpoint:
+
+```bash
+dp embed -m model.ckpt.pt -s /path/to/system -o embedding.hdf5
+```
+
+`dp embed` supports the DPA4/SeZM `.pt` checkpoint and does not support `.pt2`.
+
+## Validation
+
+- Confirm that the artifact exists and can be loaded in the target environment.
+- Inspect the stored descriptor when `.pt` could mean DPA3 or DPA4.
+- Confirm the type map before constructing `atype`.
+- Run a small finite energy/force/virial evaluation before a large batch.
+- Treat `.pt2` as a compiled deployment artifact, not a portable checkpoint.
+  Export and validate it with a device and toolchain compatible with the final
+  Python, C++, or LAMMPS runtime.
+
+## References
+
+- [DPA4 export, inference, and embeddings](https://docs.deepmodeling.com/projects/deepmd/en/latest/model/dpa4.html)
+- [Python inference](https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/python.html)
+- [Show model information](https://docs.deepmodeling.com/projects/deepmd/en/latest/model/show-model-info.html)

skills/deepmd-train/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: deepmd-train
-description: Train DeePMD-kit models with progressive disclosure. Use when the user wants to train a DeePMD-kit potential, prepare an input.json, choose between model families such as se_e2_a/DeepPot-SE and DPA3, run `dp train`, monitor learning curves, freeze checkpoints, or test trained models. Start with model selection and read only the selected model reference under `models/` when model-specific configuration is needed.
+description: Train DeePMD-kit models with progressive disclosure. Use when the user wants to train a DeePMD-kit potential, prepare an input.json, choose between model families such as se_e2_a/DeepPot-SE, DPA3, and DPA4/SeZM, run `dp train`, monitor learning curves, freeze checkpoints, or test trained models. Start with model selection and read only the selected model reference under `models/` when model-specific configuration is needed.
 compatibility: Requires deepmd-kit installed. The selected backend and model may require PyTorch, TensorFlow, JAX, Paddle, GPU support, or custom OP libraries.
 license: LGPL-3.0-or-later
 metadata:
   author: iProzd
-  version: '1.1'
+  version: '1.2'
   repository: https://github.com/deepmodeling/deepmd-kit
 ---
 
@@ -33,6 +33,7 @@ Available model references:
 | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | [`models/se-e2-a.md`](models/se-e2-a.md) | The user wants a classical DeepPot-SE baseline, broad compatibility, or a smaller/established production model.                          |
 | [`models/dpa3.md`](models/dpa3.md)       | The user wants a high-accuracy DPA3/LAM workflow, large/diverse datasets, dynamic neighbor selection, or pretrained DPA3-style training. |
+| [`models/dpa4.md`](models/dpa4.md)       | The user wants the PyTorch-only DPA4/SeZM SO(3)-equivariant architecture and its `.pt2` deployment path.                                 |
 
 ## Model selection
 
@@ -51,6 +52,7 @@ Recommended defaults:
 
 - Choose **se_e2_a** for a robust baseline, small to medium systems, compatibility-focused workflows, or when compute is limited.
 - Choose **DPA3** for high accuracy on diverse datasets, LAM-style training, or when the user explicitly asks for DPA3, DPA-3, LiGS, dynamic neighbor selection, or pretrained DPA3 variants.
+- Choose **DPA4/SeZM** when the user explicitly requests it or wants its SO(3)-equivariant message-passing architecture and accepts a GPU-oriented, PyTorch-only workflow.
 
 ## Common workflow
 
@@ -104,12 +106,16 @@ Training progress is usually written to `lcurve.out`. Check for:
 
 ### 6. Freeze and test
 
+Read the selected model reference before choosing the output format. For
+conventional PyTorch models, a typical flow is:
+
 ```bash
 dp --pt freeze -o model.pth
-dp --pt test -m model.pth -s /path/to/test_system -n 30
+dp test -m model.pth -s /path/to/test_system -n 30
 ```
 
-Adjust the backend flags and output extension for non-PyTorch models.
+DPA4/SeZM checkpoints instead freeze to `.pt2`; follow `models/dpa4.md`.
+Adjust the backend and output format for other model families.
 
 ## Agent checklist