Python API

Python methods for robots, models, deployments, and fleets.

Client

import os

import servo

sv = servo.Servo(
    base_url=os.environ["SERVO_BASE_URL"],
    api_key=os.environ["SERVO_API_KEY"],
)

The main types are servo.Servo, servo.Robot, servo.Model, servo.HostedDeployment, servo.Fleet, and servo.ConnectedRobot. The lower-level session API uses servo.Policy, servo.Session, servo.Observation, and servo.ActionPrediction.

Namespaces

Namespace	Use
sv.robots	Register, list, resolve, and attach robots
sv.models	Find models compatible with a robot
sv.deployments	Resolve hosted deployments
sv.fleets	Share hosted capacity across robots

Robots and models

Use the CLI for file-based robot setup. In Python, resolve the saved robot and its compatible models:

from my_robot_app import open_yam

record = sv.robots.get("yam-cell-01")
robot = sv.robots.attach(record, runtime=open_yam)
compatible_models = sv.models.for_robot(robot)

sv.models.for_robot() returns models whose camera, joint-state, and action requirements match the robot. sv.robots.attach() accepts a registered robot name string, a Robot record instance, or a custom robot manifest path (manifest=..., configuration=...). Use sv.robots.list() for the saved inventory and sv.robots.catalog() for supported robot types. Robots defines the runtime and custom-integration interfaces.

Use servo robot setup for registration. It sends an ordered fingerprint of the local configuration files and leaves their contents on the robot computer.

Deploy and run

model = sv.models.get("pi0.5")
deployment = model.deploy(robot=robot).wait(timeout_s=900)
policy = deployment.policy(
    robot,
    instruction="place the red lid on the black box",
)
robot.check(policy)
report = robot.run(policy, seconds=120)

model.deploy() creates a deployment. Reuse it on later runs:

deployment = sv.deployments.get("dep_...").wait(timeout_s=900)

Review active deployments with servo deployment list, and stop unused capacity with servo deployment stop <deployment-id>.

Use robot.run() for normal operation. The lower-level API exposes one observation and action for debugging an integration:

with robot, sv.session(policy) as session:
    observation = robot.observe()
    prediction = session.act(observation)
    robot.execute(prediction)

robot.observe() captures camera frames and joint states adhering to the sensor contract. session.act(observation) queries the hosted model and returns an ActionPrediction chunk. robot.execute(prediction) applies action-jump limits and streams joint targets to the local controller.

Fleets

model = sv.models.get("pi0.5")
fleet = sv.fleets.deploy(
    model,
    robots=["yam-cell-01", "yam-cell-02"],
    name="yam-assembly",
    peak_active=2,
)

robots accepts stable names or rob_* IDs. A selector such as {"site": "sf-lab", "labels": {"line": "assembly"}} selects a fixed inventory snapshot.

policy = fleet.policy(robot, instruction="place the red lid on the black box")
fleet.update("ckpt_...")
fleet.rollback()