Configuration

The config system is intended to make Python, YAML, CLI, and Studio payloads use the same workflow shape.

physicalai run --config runtime.yaml

Layers

Config
  typed constructor args for one class

ComponentSpec
  target + args for one instantiable component

Workflow config
  user-authored workflow before execution

Manifest
  exported package metadata after build/export

Orchestrator
  live object that executes the workflow

ComponentSpec

Direct class mode:

class_path: physicalai.capture.UVCCamera
init_args:
  device: /dev/v4l/by-id/usb-Example_Camera-video-index0
  width: 640
  height: 480

Tip: Use stable device paths (/dev/v4l/by-id/...) in config files. Index-based paths like /dev/video0 can change after reboot.

Registry mode:

type: uvc
device: /dev/v4l/by-id/usb-Example_Camera-video-index0
width: 640
height: 480

If both class_path and type are present, class_path takes precedence.

Typed Config

Typed configs are useful when constructor validation and IDE support matter.

@dataclass
class Pi05Config(Config):
    chunk_size: int = 50
    n_action_steps: int = 50

    def __post_init__(self) -> None:
        if self.n_action_steps > self.chunk_size:
            raise ValueError("n_action_steps must be <= chunk_size")

Typed configs do not decide which class to instantiate. They only validate and carry constructor arguments.

cfg = Pi05Config(chunk_size=50)
policy = instantiate_obj(cfg, target_cls=Pi05)

Execution Boundary

Configuration objects remain passive data. Orchestrators are responsible for creating live objects and executing workflows.

config = RuntimeConfig.load("runtime.yaml")
runtime = PolicyRuntime.from_config(config)
runtime.run()