Adapters

Write an adapter

An adapter runs in an eval between a benchmark and a policy that do not speak the same way: it turns the benchmark’s observation into what the policy reads, and what the policy returns into the benchmark’s action. You write it as two lists of transforms, each run in order. The official toy-adapter is a whole one — seq init toy-adapter writes it into a folder of your own:

import seq

# toy-benchmark observes {"arm_x": [x], "target": [t]} and takes one number a step;
# toy-policy reads {"state": [x], "target": [t]} and returns {"delta": [dx]}
@seq.adapter(name="toy-adapter")
class ToyAdapter(seq.Adapter):
    policy_io = "own"             # the policy has its own inputs and outputs

    obs_transforms = [                # the benchmark's observation → the policy's inputs
        seq.tf.rename({"arm_x": "state"}),
    ]
    action_transforms = [             # the policy's answer → the benchmark's action
        seq.tf.custom("delta_to_step", lambda out: [[float(out["delta"][0])]]),
    ]

• obs_transforms start from the benchmark’s observation — the dict its environment’s observe() returns — and end at what the policy is sent.
• action_transforms start from the policy’s answer and end at the benchmark’s action: a list of rows, one per step, each as long as the benchmark’s action_contract declares. The benchmark’s step() is handed them one row at a time.
• policy_io says which kind of policy it feeds (A preset or your own). "robot_arm", the default: the last obs_transforms step produces the preset’s cameras and state, which the platform packs with the task’s instruction, and action_transforms start from the policy’s chunk. "own": obs_transforms produce exactly the policy’s inputs — what its client.py does on a real robot — and action_transforms start from its answer as it returned it.

seq deploy toy-adapter/adapter.py registers it as toy-adapter@v1 — nothing is built or run — and an eval names it: seq eval run toy-policy --benchmark toy-benchmark --adapter toy-adapter. An adapter takes parameters the way a policy does, through its __init__ (Parameters in an eval); what it may import, its versions and how to pull one back are under Adapters.

Check it before an eval

seq adapter check runs both lists without an eval and without a GPU, on samples of what each side gives:

$ seq adapter check toy-adapter/adapter.py --benchmark toy-benchmark-cpu --policy toy-policy
adapter     toy-adapter  ToyAdapter (adapter:ToyAdapter)  policy_io own
  obs    rename(arm_x->state)
  action custom(delta_to_step)
benchmark   toy-benchmark-cpu v1: {arm_x: 1 float64, target: 1 float64}  (its registration check's first observation)
  obs    rename(arm_x->state): {arm_x: 1 float64, target: 1 float64} -> {target: 1 float64, state: 1 float64}
policy      toy-policy v1: takes ['state', 'target'] (its io= note); the adapter gives ['state', 'target'] - ok
policy      toy-policy returns {delta: 1 float64}
  action custom(delta_to_step): {delta: 1 float64} -> 1x1 float64
  -> 1x1 float64; the benchmark takes actions of 1 - ok
ok: the transform pipeline is well-formed, and it fits; nothing was run on the platform

With --benchmark, a sample shaped like the benchmark’s first observation — its keys, shapes and dtypes, read when it was registered — goes through obs_transforms one step at a time. With --policy — a deployment’s name, or a policy file of your own — what comes out is compared with what the policy reads, and a sample of what the policy returns goes back through action_transforms and is compared with the benchmark’s action. Every mismatch is printed, and any one ends the command non-zero, so it can gate a CI job. The adapter can be a file or a registered name@vN; a check against a benchmark or a policy is kept with that version for its page in the console, and --no-record keeps nothing.

Write your own transform

When no built-in transform does a step, write it: seq.tf.custom(name, fn). fn takes the value the list holds at that point and returns the next one.

• In obs_transforms, fn gets the observation dict as the steps before it left it, and returns a dict.
• In action_transforms, it gets the policy’s answer — a preset policy’s chunk, whose steps each hold their values, or its own outputs with policy_io = "own" — or what the step before returned. The last step returns the benchmark’s rows, one list of numbers a step: seq.tf.custom("to_sim", lambda chunk: [s.values for s in chunk.steps]). The official adapters (libero-openpi among them) turn actions this way.
• name names the step wherever the list is shown: seq adapter check prints each step as custom(name) with what it took and gave, and a step that fails by its name — obs step custom(joints_only) failed on {...}: KeyError: 'qpos'.
• An error in fn is raised as it is. At an eval’s first act, one in obs_transforms stops the eval as a mismatch: the adapter could not map the benchmark's observation, then your error.

import numpy as np    # what the benchmark's image installs

def joints_only(obs):                 # the observation dict → the next one
    return {**obs, "state": np.asarray(obs["qpos"], dtype=np.float32)[:7]}

def to_rows(out):                     # the policy's outputs → the benchmark's rows
    return [[float(v) for v in row] for row in out["actions"]]

obs_transforms = [seq.tf.custom("joints_only", joints_only), seq.tf.drop(["qpos"])]
action_transforms = [seq.tf.custom("to_rows", to_rows)]

Built-in transforms

The common steps, each one line. Each takes the observation dict and returns the next one — action_project, the policy’s chunk — and none changes a value it does not name.

A key a transform names that the dict does not hold — reshape or downcast on a missing key — raises Python’s KeyError for it.

When an adapter is refused

@seq.adapter reads the class as soon as its file is imported — by seq deploy, seq adapter check or your own test — and refuses it there, before anything is registered: