physicalai-train-adding-a-policy
Adds or modifies a Physical AI Studio policy under library/src/physicalai/policies. Use when creating a new policy family with the config/model/policy split, registering it in the get_policy factory and package exports, or keeping a policy compatible with Lightning training and export. Covers Pi0.5, Pi0, ACT, GR00T, SmolVLA, and LeRobot-wrapped policies.
How do I install this agent skill?
npx skills add https://github.com/open-edge-platform/physical-ai-studio --skill physicalai-train-adding-a-policyIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides architectural guidance and development workflows for adding machine learning policies to the Physical AI Studio framework. It outlines file structures, interface requirements, and testing procedures using project-specific tools like physicalai and uv without any security concerns.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Adding a Studio Policy
Policies live in library/src/physicalai/policies/<name>/. Each family is a Lightning-facing Policy wrapping a torch.nn.Module Model, split across three files. Base classes are in policies/base/ (Policy in policy.py, Model in model.py); shared Config / FromConfig types come from Runtime (physicalai.config) — see Runtime docs use-from-config and configuration.
Workflow
-
Read a nearby family first. Study
policies/pi05/(current reference implementation):config.py(Pi05Config(Config)),model.py(Pi05Model(Model)),policy.py(Pi05(ExportablePolicyMixin, Policy)),preprocessor.py, and any extra modules the architecture needs (e.g.pi_gemma.py). For a deliberately minimal family,policies/act/is a smaller three-file layout without the VLM stack.- Done when: you can name which existing file each new file mirrors.
-
Create the three-file split in
policies/<name>/:config.py—<Name>Config(Config), all hyperparameters as typed fields.model.py—<Name>Model(Model), puretorch.nn.Modulelogic.policy.py—<Name>(Policy)(addExportablePolicyMixinonly when export is implemented).- Done when:
from physicalai.policies.<name> import <Name>, <Name>Config, <Name>Modelimports cleanly.
-
Implement the policy interface used by both training and inference through the base
Policy:forward(...)— training path; return values compatible withtraining_step.predict_action_chunk(...)— inference path; return a tensor with the configured action horizon.select_action(...)— use base-class action-queue behavior unless a specialized flow is justified.- Done when: shapes match the checks below for a synthetic batch.
-
Register the family so both API and CLI users can find it:
- Add exports to
policies/__init__.py(__all__and imports, e.g.<Name>,<Name>Config,<Name>Model). - Add the lowercase name to the
get_physicalai_policy_class(...)/get_policy(...)dispatch inpolicies/__init__.py. - Done when:
from physicalai.policies import <Name>, get_policyworks,get_policy("<name>")returns an instance, and--model physicalai.policies.<Name>resolves.
- Add exports to
-
Prove direct API construction before adding CLI config:
from physicalai.policies import get_policy policy = get_policy("<name>")- Done when: direct construction, config round-trip, and synthetic
forward(...)/predict_action_chunk(...)shape checks pass.
- Done when: direct construction, config round-trip, and synthetic
-
Add a training config in
library/configs/physicalai/<name>.yamlwhen the policy is user-facing from the CLI. Wiremodel.class_path, adata.class_path(usuallyphysicalai.data.lerobot.LeRobotDataModule), andtrainer.*. Mirrorconfigs/physicalai/pi05.yaml.- Done when:
physicalai fit --config configs/physicalai/<name>.yaml --trainer.fast_dev_run=truecompletes one step.
- Done when:
-
Wire export only when ready. Add
ExportablePolicyMixinand a valid sample input, then follow thephysicalai-train-exporting-and-validatingskill. If export is intentionally unsupported, say so explicitly in the policy docstring. -
Add tests under
library/tests/unit/policies/next to existing policy tests: at least one construction/config path and one shape-validation test.- Done when:
uv run pytest tests/unit/policies -k <name>passes.
- Done when:
-
Update docs if the policy is user-visible:
library/docs/explanation/policy/and any config/API examples.
Required checks
Account for every item below (not just "looks fine"):
- Action shape semantics — batch, horizon/chunk length, and action dimension are correct and unchanged from the family's convention.
- Observation features — feature names align with dataset/config conventions (
data/observation.py:Feature,FeatureType). - API construction path — imports,
get_policy(...), direct constructor use, and synthetic shape checks pass without CLI involvement. - Config path — construction works through the jsonargparse CLI path used by
physicalai fit(class_path/init_args) when the policy is CLI-visible. - Heavy dependencies — gate large families behind an optional extra in
library/pyproject.tomland import lazily, matchingpi05/pi0/groot/smolvla. - No silent contract changes — do not alter action dims, feature names, or preprocessing without coordinating export/Runtime.
Verify
From library/:
uv run pytest tests/unit/policies -k <name>
physicalai fit --config configs/physicalai/<name>.yaml --trainer.fast_dev_run=true
prek run --all-files library/
References
references/base-classes.md— thePolicy/Modelcontract and file-split expectations.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/open-edge-platform/physical-ai-studio/physicalai-train-adding-a-policy">View physicalai-train-adding-a-policy on skillZs</a>