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

# Python API

> Inspect, deploy, predict and stop.

Install with `pip install servo-client`; authenticate with `servo login`.
For runnable CLI/Python examples, use the [quickstart](/quickstart).
These signatures show common options.

## Client and models

```text theme={null}
servo.Servo(base_url=None, api_key=None, timeout=3600.0) -> Servo
sv.models.inspect_checkpoint(source, *, revision="main", secret=None) -> ModelInspection
sv.models.import_checkpoint(source, *, revision="main", name=None, wait=True, timeout_s=2400) -> Model
sv.models.get(slug) -> Model
sv.models.list() -> list[Model]
model.wait(*, timeout_s=2400) -> Model
model.deploy(robot=None, *, city=None, region=None, latitude=None, longitude=None, deployment_key=None, idle_minutes=None, max_sessions=None) -> Deployment
```

`source` accepts a Hugging Face URL, `hf://ORG/REPO`, or `ORG/REPO`.
Pin `revision` to a commit for reproducibility.
Inspection exposes `input_contract`: resolution, input names/shapes/dtypes and output shape.
Import waits for preparation unless `wait=False`.

Choose one placement: `city`, `region`, coordinates, or a robot's saved site.
The same model and site reuse a deployment; `deployment_key` distinguishes separate deployments.
Capacity stays warm until stopped unless `idle_minutes` is set.

## Deployments

```text theme={null}
sv.deployments.get(deployment_id) -> Deployment
deployment.wait(*, timeout_s=2400) -> Deployment
deployment.policy(robot=None) -> Policy
deployment.delete() -> Deployment
deployment.wait_retired(*, timeout_s=300) -> Deployment
```

Read `id` and `status`; `wait` confirms readiness.
A timeout leaves allocation running.
`delete` requests shutdown; `wait_retired` confirms it.

## Predictions

```text theme={null}
sv.session(policy, *, instruction=None) -> Session
session.predict(*, inputs, instruction=None) -> ActionPrediction
session.act(observation, instruction=None) -> ActionPrediction
session.close() -> None
sv.sessions.list(*, robot=None) -> list[SessionRecord]
sv.sessions.get(session_id) -> SessionRecord
```

Use sessions as context managers; listed session records are read-only.
`predict` accepts checkpoint-named arrays; `act` accepts structured observations.
A per-call instruction overrides the session default for that request.

| Value | Meaning |
| - | - |
| `inputs` | `Mapping[str, Any]`: inspected feature names to matching NumPy arrays |
| `chunk.actions` | Action rows, shaped `[horizon, action_dim]` |
| `chunk.horizon`, `chunk.action_dim` | Rows and channels per row |
| `chunk.telemetry`, `chunk.raw` | Returned timing and response details |

Extra input keys, including `metadata`, are rejected for checkpoint-named inputs.
Servo handles preprocessing. Your robot application owns action execution and sensor capture.
Closing a session leaves the deployment running.

## Robots and access

```text theme={null}
sv.robots.get(name_or_id) -> Robot
sv.robots.list() -> list[Robot]
sv.access.grant(subject, *, robot, role) -> None
sv.access.revoke(subject, *, robot) -> None
sv.access.list(*, robot) -> list[Grant]
```

Robot identity is optional for checkpoint inference.
`subject` is a member email or Google Group; `role` is `read`, `write` or `admin`.
See [identity and access](/guides/identity).

<Accordion title="Local recovery">
  For a custom controller, see [local recovery](/guides/local-recovery).

  ```text theme={null}
  session.open() -> Session
  session.configure_recovery(*, handler, controller, takeover_timeout_s=1.0) -> RecoveryRegistration
  registration.notify_starvation(*, queue=None) -> None
  registration.stop() -> Awaitable[None]
  recovery.resume(*, timeout_s=10.0) -> Awaitable[ResumeResult]
  recovery.hold(reason) -> str
  recovery.release_hold(token) -> None
  recovery.record_action(name, *, outcome, details) -> None
  ```
</Accordion>

Errors expose `code`, `message` and `detail`; see [errors](/reference/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.