> ## Documentation Index
> Fetch the complete documentation index at: https://servo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Python API

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

## Client

```python theme={null}
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:

```python theme={null}
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](/guides/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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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.

```python theme={null}
policy = fleet.policy(robot, instruction="place the red lid on the black box")
fleet.update("ckpt_...")
fleet.rollback()
```