physicalai-runtime-loading-exported-policies

name	physicalai-runtime-loading-exported-policies
description	Loads and validates policies exported from Physical AI Studio for Runtime deployment. Use when working on InferenceModel, InferenceModel.from_pretrained, manifest.json, adapter auto-detection (onnx, openvino), backend/device kwargs, Hugging Face Hub policy packages, or the Runtime side of the export/load contract that Studio produces with physicalai export.
license	Apache-2.0

Loading Exported Policies

Runtime loads Studio export directories (or Hub snapshots that mirror them) through InferenceModel in src/physicalai/inference/model.py. Manifest parsing lives in src/physicalai/inference/manifest.py; backends register in src/physicalai/inference/adapters/registry.py (onnx → .onnx, openvino → .xml). Hub downloads use src/physicalai/inference/utils/_hub.py.

Workflow

1. Identify the artifact: local export directory or Hub repo_id, expected backend, and whether the user needs select_action vs predict_action_chunk.

   • Done when: load path and API entry point are chosen before editing code.

2. Load with auto-detection first (local):

   from physicalai.inference import InferenceModel
   model = InferenceModel("./exports/act_policy")
   

   • Done when: model constructs without explicit backend= when artifacts match a registered extension.

3. Hub load when the package is published:

   model = InferenceModel.from_pretrained("OpenVINO/act-fp16-ov", revision="<commit-sha>")
   

   • Done when: revision is pinned for reproducibility when security or CI matters.

4. Explicit backend only when auto-detection is ambiguous:

   model = InferenceModel("./exports/act_policy", backend="openvino", device="CPU")
   

5. Validate structure against references/export-load-contract.md and backend notes (references/onnx.md, references/openvino.md).

   • Done when: manifest, model file, and processor artifacts resolve under the export directory.

6. Smoke inference without owning robot timing:

   model.reset()
   action = model.select_action(observation)
   

   • Done when: one forward pass succeeds on representative observation keys/shapes. For hardware loops, hand off to physicalai-runtime-running-policy-on-robot.

Validation loop

uv run pytest tests/unit/inference/test_model.py tests/unit/inference/test_manifest.py -q

For adapter changes, add or run targeted tests under tests/unit/inference/.

Required checks

• Export directory contains backend model file(s) and manifest.json consistent with docs/reference/manifest-schema.md.
• Metadata input/output/feature names align with preprocessors in the manifest.
• Optional backends fail with clear install guidance (onnxruntime, OpenVINO).
• Do not document a backend unless an adapter is registered in src/physicalai/inference/adapters/.
• Hub loads must not log tokens; prefer pinned revision= for production docs.

References

• references/export-load-contract.md — consumer-side contract (coordinate with Studio export skill).
• references/onnx.md, references/openvino.md — adapter constraints.