Author a policy

The @seq.policy class

A policy is a class decorated with @seq.policy: the arguments declare what it needs (GPU, image, weights); the methods mark what runs when. seq init pi05-droid clones a decorated pi0.5 template to repoint at your own checkpoint.

import seq

@seq.policy(
    gpu="L4",                                  # any card seq gpus lists
    max_gpus=2,                                # required: the most GPUs at once, one robot each
    image=(
        seq.Image.debian_slim()                # a small, pinned Debian base
        .apt_install("libgl1", "libglib2.0-0")
        .run_commands("git clone https://github.com/Physical-Intelligence/openpi /opt/openpi",
                      "cd /opt/openpi && uv pip install --system -e .")   # openpi installs from source
    ),
    weights=seq.Volume.from_name("pi05-ft"),   # your checkpoint: an uploaded volume, hf://, or a template's
    secrets=[seq.Secret.from_name("hf")],      # optional, by name only — see Secrets
)
class Pi05(seq.Policy):
    @seq.load                                  # cold start, once: pull the checkpoint into VRAM
    def load(self, weights_dir):
        self.model = ...
    @seq.warmup                                # optional: one JIT-warming pass before serving
    def warmup(self):
        ...
    @seq.infer                                 # per request: observation -> ActionChunk
    def infer(self, obs, *, seed=None):
        return self.model(obs)
    @seq.on_episode                            # optional: a stateful policy's episode boundary
    def on_episode(self, episode_id):
        ...
    @seq.shutdown                              # optional: cleanup before the worker stops
    def shutdown(self):
        ...

Decorator and lifecycle

The decorator arguments:

The methods bind to lifecycle stages. Only @seq.load and @seq.infer are required; the rest are opt-in.

Compilation is kept between cold starts. Each deployment has its own cache volume: the JAX, torch.compile and Triton caches point at it, and what the first worker compiled is saved once it is ready. A later worker reads it instead of compiling again — pi0.5 on an L4 loads in 53 s instead of 80 s. A worker keeps the platform code its version was built with, so a version built before an improvement like this one gets it when you deploy again.

How load and infer are called

load and infer are your code; the platform decides when they run. It copies the weights you declared into a directory, calls load once with that directory, then calls infer for every request. Reading the files and building the model are load’s job.

• weights_dir is /data/<policy name>: the directory weights= is copied to before the worker starts. Weights in named parts (weights={"base": …, "lora": …}) arrive as {name: directory} instead.
• With no weights declared, nothing is copied and load is still called once, with that path. toy-policy keeps it and builds nothing; pi05-droid builds the model from it with openpi (create_trained_policy(cfg, weights_dir, …)).
• load may take up to the startup limit of timeouts= (1800 s by default; see the table above).
• Which inputs infer gets depends on how it is written: if its first argument is annotated Observation or it returns an ActionChunk, the worker parses each request into an Observation and checks it against the contract you declared (The I/O contract); otherwise infer gets the request’s inputs as they were sent (Your own inputs and outputs).

Your own inputs and outputs

A policy that declares no contract defines its own inputs and outputs. The platform converts nothing: it hands infer the dict the caller sent, unchanged, and sends back whatever infer returns. The format is yours to choose, so write it where callers will look — infer’s docstring and your README. toy-policy takes {"state": [x], "target": [t]} and returns {"delta": [dx]}.

• From a robot or a script, send that dict and get the outputs back as infer returned them: sequence_ai.connect("my-toy").predict({"state": [0.0], "target": [0.5]}) returns {"delta": [0.1]}. A template’s client.py builds the dict for you.
• In an eval, an adapter turns the benchmark’s observation into your inputs and your outputs into the benchmark’s action: one with policy_io = "own" hands infer exactly the dict it takes (see Adapters).
• A wrong key is not caught before infer runs, because nothing knows your format: inputs["state"] on a request that sent arm_x raises inside your code, and the caller gets that error: a Python built-in exception comes back as itself — here KeyError: 'state' — with your code’s traceback on .remote_traceback (any other type arrives as PolicyError, its name in .exception_type). It is a 500 policy_error, so a caller can tell your code’s failure from the platform’s. Check the keys you need at the top of infer and raise an error that names them, as toy-policy does — or declare a contract and let the worker check for you.

The I/O contract

Declare what infer returns and what it reads. The worker then refuses an observation the policy cannot read — a missing camera, too few frames, a state vector of the wrong length, an empty instruction — with a 400 before any inference runs, and refuses a chunk that is not the declared action space or dimension. When you deploy, the build sends one synthetic observation made from the contract (black frames, zero vectors) to /act; anything but a 200 fails the build with your policy’s own error. A policy that declares nothing is not checked.

@seq.policy(
    gpu="L4", max_gpus=1, weights="hf://my-org/pi05-ft",
    action=seq.ActionContract(
        robot="franka",
        action_space=seq.ActionSpace.JOINT_DELTA,     # JOINT_ABSOLUTE, JOINT_DELTA, JOINT_VELOCITY, EE_ABSOLUTE, EE_DELTA
        action_dim=8,
        control_frequency_hz=15.0,
        bounds=[(-0.05, 0.05)] * 7 + [(0.0, 1.0)],  # optional: each dimension's [low, high]
        max_delta=0.05,                                # optional: the most one step moves from the last
        on_violation="clip",                           # "clip" (default) or "refuse"
    ),
    observation=seq.ObservationContract(
        cameras={"exterior": seq.Camera(width=224, height=224),
                 "wrist": seq.Camera(width=224, height=224)},
        proprio={"joint_positions": 7, "gripper": 1},
        history=1,                                     # frames per camera the policy reads
    ),
)

• Limits. With bounds or max_delta the worker clips every chunk into them and lists each clipped step in the response’s warnings; the client clips again across chunks before an action reaches your robot. on_violation="refuse" answers an error instead of a clipped chunk.
• Check before the arm moves. connect(model, expect={"action_space": "joint_delta", "action_dim": 8}) compares what you will execute with what the deployment declared, and raises before the first action if they differ. policy.contract holds the declared contract.
• Depth. seq.Camera(width=, height=, depth=True) declares that the view also sends a depth frame. sequence_ai.observation(images=..., depth={"wrist": depth_map}) sends each map as a lossless 16-bit PNG of millimetres (metres in by default; depth_unit="mm" for a map already in millimetres). A declared depth frame that is missing is refused before inference.

Inference parameters

A keyword argument of infer with a default is an inference parameter. Annotate it int, float, bool or str; seq validate lists them. A robot sets them for its whole session with connect(model, params={"replan_steps": 3}); an eval sets one with --param or compares values with --sweep (an adapter’s and a benchmark’s too: Parameters in an eval); a raw /act request sets them in its "params" object. A name the policy did not declare is refused before inference, and each value is cast to its declared type.

A parameter can also say which values it takes: bound a number with Annotated[int, seq.Range(1, 10)] (or seq.Range(min=0.0)), or list its values with Annotated[str, seq.OneOf("fast", "careful")]. Any other value is refused before inference, saying what is allowed — at connect, by seq policy params, by an eval before anything is reserved, and by the worker on a raw /act; seq validate shows the range beside each parameter (sequence-ai 0.33.27 and later).

A deployment’s defaults change without a redeploy: seq policy params <name> replan_steps=10. Every session that connects from then on runs with them unless it names its own; a robot already connected learns of them at its next lease renewal, within about five minutes, and switches at its next episode (sequence-ai 0.33.27 and later; 0.33.21 to 0.33.26 switch at the renewal itself, an older client runs with its own and the policy’s). An eval of the policy runs with them too unless it sets its own with --param, and its report marks those values deployment’s default (reading such a report needs sequence-ai 0.33.28 and later). --clear replan_steps removes one, seq policy params <name> shows them beside what the policy declares, and seq policy status <name> lists what each connected robot runs with.

@seq.infer
def infer(self, obs, *, seed=None, replan_steps: Annotated[int, seq.Range(1, 10)] = 5,
          temperature: float = 0.0):
    ...

# $ seq eval run my-pi05 --benchmark libero-custom --param replan_steps=3
# $ seq eval run my-pi05 --benchmark libero-custom --sweep replan_steps=3,5,8

Pacing on a real robot

Three numbers decide whether an arm keeps moving between chunks. The control rate — actions per second — belongs to the model and the data it was trained on: each action means “move this much in this step”, so it is not a knob. The actions run per call (replan_steps in the templates) is: how many of a chunk’s actions the robot runs before it asks again. And one call’s round trip is the policy’s inference plus the network. Each call buys replan_steps ÷ control rate seconds of motion, and the SDK asks for the next chunk while they run; when that is shorter than a round trip, the arm stops and waits on every chunk.

A simulator waits for each action, so an eval can ask often — more closed-loop, usually more successes; a real robot does not wait. Run enough actions per call to cover a round trip, and measure what it costs in an eval first: seq eval run <policy> --benchmark <name> --sweep replan_steps=5,10.

Batching requests

With @seq.batched the worker runs acts that are waiting together as one call — up to max_batch_size: each argument of infer receives a list with one entry per request (the observations, the seeds, every inference parameter), and it returns a list of chunks in the same order. A batch raises throughput, not one robot’s speed: pi0.5 on an L4 answers one observation in 232 ms and sixteen in 2270 ms — 1.6 times the requests per second, each of them slower.

• In an eval, many environments act at once, and their acts reach a policy instance spread over up to a few hundred milliseconds: it gathers them until they stop coming — a batch runs once eval_wait_ms (20 ms unless you name it) pass with no new act, once it is full, or 250 ms after its first act at the latest.
• A deployment serving robots never waits: a robot’s acts come one at a time, so a wait would only delay each of them. Acts that arrive while a copy is busy still run together when it frees, at no extra wait. Only a deployment that crowds robots onto a copy (@seq.concurrent with max_inputs above its copies) may name serve_wait_ms, at most 10 ms.

@seq.batched(max_batch_size=16, eval_wait_ms=20)  # 2-256 requests; an eval's batch runs once 20 ms pass with no new act
@seq.infer
def infer(self, obs, *, seed=None):
    return self.model.batch(obs)                 # obs is a list; return one ActionChunk per entry

wait_ms= is the old name of eval_wait_ms=: still read, with a warning. Not for streaming=True: a stateful episode owns its replica.

Images

Each seq.Image method returns a new image; the chain is a spec, and the step order you write is the build order.

Volumes and weights

weights= copies the checkpoint once, at deploy, into a volume the worker mounts at /data; every cold start reads that copy. The volume is billed as storage at the size actually copied. It names one of three things:

• An official template’s weights — seq.Weights.template("pi05-droid", version=1) (the string form is "template://pi05-droid@v1"): the unmodified checkpoint a template ships with, plus what it loads at runtime (pi0.5’s tokenizer). A published version never changes; leave version= out to take the newest one at each deploy. No key is needed. This is what seq init pi05-droid writes.
• Hugging Face — hf://org/model or hf://org/model@<revision>. The revision is resolved to a commit at deploy and exactly that commit is copied, so a re-deploy is deterministic. A private or gated repo needs a token: seq secret set hf --env HF_TOKEN, then secrets=[seq.Secret.from_name("hf")]. The copy runs with only that token; declaring it also hands HF_TOKEN to your policy at runtime. A repo that cannot be read is refused when you deploy, in seconds, with what to fix.
• Your own files — upload a checkpoint directory once with seq volume put pi05-ft ./checkpoints/pi05-ft (resumable: run it again after an interruption), then deploy it by name: weights=seq.Volume.from_name("pi05-ft"), or weights="vol://pi05-ft@v2" to pin a version. Every file’s md5 is checked when the upload completes; only then is the version active and billed as storage. seq volume ls lists them; seq volume rm is refused while a deployment’s weights, or a registered benchmark’s assets, use the volume.
• Several parts — a dict of named parts, each from its own origin and read with its own declared secret; @seq.load receives {name: directory}. Up to 8 parts, named [a-z][a-z0-9_-]: weights={"base": "hf://physical-intelligence/pi05-base", "lora": seq.Volume.from_name("my-lora"), "norm_stats": seq.Volume.from_name("droid-norm")}.

Deleted a volume, or replaced a version with a new seq volume put, by mistake? Contact us within 7 days and we can bring it back.

Weights from your own storage bucket or an https URL are deprecated. This SDK release still deploys them, with a warning; the next one refuses them. Move the files into a volume once — download them, then seq volume put <name> <dir> — and deploy weights=seq.Volume.from_name("<name>"), or point at the Hugging Face repo they came from.

Explicit volumes= mounts are coming — a deploy that declares volumes= now is refused rather than run without it.

A policy with no checkpoint — a closed-form controller, say — leaves weights= out: nothing is copied or mounted, and nothing is billed as storage. seq validate shows weights none.