Metadata-Version: 2.4
Name: servo-client
Version: 0.2.0
Summary: Python SDK for Servo's hosted robot model API
Project-URL: Documentation, https://servo.mintlify.site/
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=42
Requires-Dist: httpx[http2]
Requires-Dist: msgpack>=1.0.5
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2
Requires-Dist: protobuf<7,>=6.33.6
Requires-Dist: websockets>=13
Provides-Extra: livekit
Requires-Dist: livekit==1.1.14; extra == "livekit"

# servo-client

The public Python SDK and customer CLI for Servo robot policies, world models, datasets, jobs, and
deployments.

## Install

```bash
pip install 'servo-client>=0.2,<0.3'
```

Servo releases two architecture-specific Linux wheels containing the native Quinn action-session
binary, one portable wheel, and a source distribution. Native clients prefer a validated QUIC
route; WSS and H2 binary remain ordered pre-inference fallbacks. Portable installations use the
advertised non-native routes. Every route carries the same ActionSession v4 Protobuf frames.

LiveKit is an explicit optional transport:

```bash
pip install 'servo-client[livekit]>=0.2,<0.3'
```

## Configure the control plane

Servo has no compiled-in hosted URL. Set the origin supplied by your Servo administrator so an old
package cannot silently send credentials or robot traffic to a retired deployment:

```bash
export SERVO_BASE_URL='https://<your-servo-control-plane>'
```

The client also accepts `base_url=` explicitly. The argument takes precedence over the environment.

## Sign in

The distribution installs the customer-safe `servo` CLI:

```bash
servo login
servo whoami
servo key create --label laptop
servo deployment list
```

Serving, benchmarking, profiling, and platform-operator commands belong to the private
`servo-platform` distribution and are not installed by `servo-client`.

## Quickstart

```python
import os

import servo
from servo import templates

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

robot = sv.robots.register(templates.so101())
observation = templates.sample_observation(robot)
model = sv.models.get("smolvla")

report = model.inspect(robot)
if not report.compatible:
    raise RuntimeError(report.issues)

prediction = model.policy(robot, instruction="pick up the cube").act(observation)
print(prediction.actions[0])
```

## Action sessions

`sv.session(policy)` negotiates the transports advertised by the selected deployment. Once an
inference request could have executed, Servo never replays it over another route.

LiveKit requires both deployment and session opt-in:

```python
provider = servo.ServingProvider(os.environ["SERVO_SERVE_PROVIDER"])
deployment = model.deploy(
    robot,
    serve_provider=provider,
    action_session_channels=("livekit", "wss"),
)
policy = deployment.policy(robot, instruction="pick up the cube")

with sv.session(
    policy,
    action_session=servo.ActionSessionOptions(channels=("livekit",)),
) as session:
    prediction = session.act(observation)
```

## Public boundary

Application compatibility is promised for documented imports from `servo` and these client
namespaces:

- Stable: `robots`, `adapters`, `models`, `datasets`/`data`, `deployments`, `jobs`, `licenses`, and
  `secrets`.
- Advanced: direct endpoint helpers (`servo.connect`, `servo.attach`, `EndpointGrant`) and
  `sv.self_hosted`.

The distribution also carries dependency-light support packages:

- Extension contracts: `servo_action_session`, `servo_data`, and `servo_observation`.
- Implementation dependencies: `servo_contracts` and `servo_telemetry`.

Importability of an implementation package is not a customer compatibility promise. The client
wheel excludes product-only profiler integration and does not contain `servo_platform`,
`servo_runtimes`, FastAPI routes, database models, provider launchers, provider credentials, or
private endpoint URLs.

## Failure and retry policy

The client does not automatically replay mutations or robot actions. Transport and server failures
are returned as typed Servo errors so applications can choose a recovery policy appropriate to the
operation. Idempotent reads may be retried by application code. Configure `timeout=` on
`servo.Servo`; long-running synchronous jobs can require a larger read timeout than catalog calls.

## Requirements

- Python 3.12+
- A Servo control-plane URL
- An organization API key for authenticated operations

Full documentation: <https://servo.mintlify.site/>
