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

# ServiceClient

> Create runs and samplers, manage the Loops session, and list checkpoints.

`ServiceClient` creates a session, then creates training runs and samplers within that session on demand. Loops picks an [availability mode](https://docs.baseten.co/loops/availability-modes/overview.md) for each and returns the [`TrainingClient`](https://docs.baseten.co/reference/sdk/loops/training-client) and [`SamplingClient`](https://docs.baseten.co/reference/sdk/loops/sampling-client) you use for the run.

Create a training run and get a `TrainingClient`:

```python theme={"system"}
from baseten.loops import ServiceClient

service_client = ServiceClient()
training_client = service_client.create_lora_training_client(
    base_model="Qwen/Qwen3.5-2B",
    rank=16,
)
```

**ServiceClient(\*, api\_key=None, base\_url=None, reuse\_from\_run\_id=None, reuse\_from\_session\_id=None, team=None, availability\_model=None)** `ServiceClient`

Construct a `ServiceClient` and create a new `TrainerSession` on the Baseten control plane. All arguments are keyword-only. `api_key` defaults to the `BASETEN_API_KEY` environment variable, and `base_url` to `LOOPS_BASE_URL` (falling back to `https://api.baseten.co`).

Pass `team` to create the session, trainers, and samplers inside a specific Baseten team instead of your organization's default team. Give the team's name, not its ID. `ServiceClient` resolves the name against your available teams when you construct it, and raises `ValueError` listing the teams you can use when none match. `ServiceClient` reads the `LOOPS_TEAM` environment variable when you don't pass the kwarg. See [Teams](https://docs.baseten.co/organization/teams.md).

`availability_model` sets the capacity type for trainer and sampler deployments. Paired samplers inherit their run's capacity type. Pass an [`AvailabilityModel`](https://docs.baseten.co/reference/sdk/loops/types) value or its string (`"standard"` or `"spot"`). If you omit it, `ServiceClient` reads `LOOPS_AVAILABILITY_MODEL`, then defaults to `standard`. The constructor argument takes precedence over the environment variable. `"dedicated"` is accepted as an alias for `"standard"`. It applies when `scope` is `dedicated`. See [Spot capacity](https://docs.baseten.co/loops/availability-modes/dedicated.md#spot-capacity).

Pass `reuse_from_run_id` to request a prior dedicated run's warm trainer and paired sampler instead of starting new ones. Reuse requires the same capacity type. Serverless runs don't use reuse. `ServiceClient` reads the `LOOPS_REUSE_FROM_RUN_ID` environment variable when you don't pass the kwarg; the kwarg wins when you set both.

`reuse_from_session_id` (environment variable `LOOPS_REUSE_FROM_SESSION_ID`) is the deprecated session-based trainer equivalent; when both are set, the run ID wins and the session ID is ignored. Standalone sampler creation ignores session reuse and creates a new logical sampler.

The named run or session must belong to the same team. Reuse is best-effort: if the earlier run's trainer or sampler isn't available, Loops starts a new one and the call still succeeds. See [Reuse a warm run](https://docs.baseten.co/loops/availability-modes/dedicated.md#reuse-a-warm-run).

**ServiceClient.local(\*, trainer\_url, sampler\_url)** `ServiceClient`

Bind to already-running local trainer and sampler processes without contacting the control plane. Pass `trainer_url` and `sampler_url` as the base URLs of local server processes. Useful for end-to-end testing.

**create\_lora\_training\_client(base\_model, rank=32, replicas=1, seed=None, max\_seq\_len=None, timeout=600.0, ready\_timeout=3600.0, sampler\_timeout=None, wandb\_config=None, with\_sampler=False, name=None, sampler\_num\_replicas=None, scope=None, base\_checkpoint=None, base\_checkpoint\_auth=None)** `TrainingClient`

Create a run for the given Hugging Face `base_model` and return a connected [`TrainingClient`](https://docs.baseten.co/reference/sdk/loops/training-client). Blocks until the trainer endpoint is ready, so you can use the returned client immediately. By default the run has no paired sampler; one is created the first time you request a sampling client from the returned `TrainingClient`. Pass a [`WandbConfig`](https://docs.baseten.co/reference/sdk/loops/types) instance to stream training metrics to a Weights & Biases run.

`scope` selects the [availability mode](https://docs.baseten.co/loops/availability-modes/overview.md#choose-a-mode). Pass `"serverless"` to require the serverless mode, `"dedicated"` for the dedicated mode, or `"default"` to let Loops choose. If you omit it, Loops reads `BASETEN_LOOPS_SCOPE`, then uses `"default"`. `ServiceClient` also accepts `"deployment"` as an alias for `"dedicated"`.

`replicas` sets the number of data-parallel copies of a trainer deployment. More copies use more GPUs; they don't change model size or sequence length. Must be at least 1. Values above 1 bypass reuse of deployments. See [Scale the trainer](https://docs.baseten.co/loops/availability-modes/dedicated.md#scale-the-trainer) for how batches shard across replicas.

`max_seq_len` sets the longest sequence in tokens the run must handle. Omit it and Loops picks the default for the model and the accelerators available to you. In the dedicated mode, the paired sampler serves at this length too; a serverless sampler serves the sequence length serverless supports for the model.

`sampler_timeout` sets the read timeout for a single `sample()` call on the run's paired sampler. Omit it and `sample()` waits for the server. A dedicated sampler ends the request with a `504` after the platform's sampling timeout. A serverless request waits in the Loops queue until it finishes or Loops fails it, and then `sample()` raises [`RemoteOpError`](https://docs.baseten.co/reference/sdk/loops/errors). Pass a number of seconds to bound the wait, and `sample()` raises [`SampleTimeoutError`](https://docs.baseten.co/reference/sdk/loops/errors) when the wait exceeds it. Loops cancels a serverless request that hasn't started by then.

`name` sets the run's display name. Omit it and the run takes the base model name.

`with_sampler` creates the run's paired sampler up front. In the dedicated mode, its deployment starts alongside the trainer. In the serverless mode, it reserves the run's sampler capacity together with its trainer capacity; without it, the first sample waits for sampler capacity. Leave it off for train-only workloads. If sampler creation fails, the run continues and the sampler falls back to being created on first use.

`sampler_num_replicas` sets the replica count for the paired sampler in the dedicated mode, applied as both its minimum and maximum. Must be at least 1. The count takes effect when the sampler is created: eagerly with `with_sampler`, or at the first sampling request. Omit it and the backend default applies. Serverless samplers ignore this setting.

`base_checkpoint` starts the run from a merged checkpoint instead of `base_model`'s weights. Custom base checkpoints must be enabled for your workspace. [Contact us](mailto:support@baseten.co) to enable them. Pass a Hugging Face repository as `hf://<org>/<repo>`, optionally with `@<revision>`; an object store path that starts with `s3://`, `gs://`, `r2://`, `cw://`, or `azure://`; or a Baseten Training checkpoint in your team as `bt://<project>@<job_id>/<checkpoint>`. The checkpoint must share `base_model`'s architecture, which selects the hardware and training setup. You can't combine it with run or session reuse.

The SDK pins an `hf://` revision to a commit when it creates the run and loads the tokenizer from it. [`TrainingClient.base_checkpoint`](https://docs.baseten.co/reference/sdk/loops/training-client) reports the pinned value. For a private repository, set `HF_TOKEN` or run `hf auth login` where the SDK runs. Other sources use `base_model`'s tokenizer, so ship the same tokenizer files with the checkpoint. Each sampler and resumed run reads an object store or `bt://` checkpoint again. Checkpoints from these runs can't be deployed.

`base_checkpoint_auth` is the team secret Baseten reads `base_checkpoint` with, as a [`WeightsAuth`](https://docs.baseten.co/reference/sdk/loops/types): `WeightsAuth(auth_method="CUSTOM_SECRET", auth_secret_name="<secret>")`. The secret holds a Hugging Face token or the object store's credentials. `bt://` checkpoints take none. For `hf://`, it defaults to the `hf_access_token` team secret. The run, its samplers, resumed runs, and deployments all use these credentials. It requires `base_checkpoint`.

A serverless run also waits for room in the capacity pool Baseten manages. While the pool is fully committed, the call retries, then raises [`LoopsCapacityError`](https://docs.baseten.co/reference/sdk/loops/errors#param-loops-capacity-error). See [capacity and quota errors](https://docs.baseten.co/troubleshooting/loops.md#resolve-capacity-and-quota-errors).

**create\_training\_client\_from\_state(path, user\_metadata=None, replicas=1)** `TrainingClient`

Return a [`TrainingClient`](https://docs.baseten.co/reference/sdk/loops/training-client) initialized with the weights saved at `path`. The new run uses the checkpoint's base model and LoRA configuration. The optimizer starts fresh. Use this to resume from a saved checkpoint when you don't need the prior optimizer state. `replicas` works as in `create_lora_training_client`.

**create\_training\_client\_from\_state\_with\_optimizer(path, user\_metadata=None, replicas=1)** `TrainingClient`

Return a [`TrainingClient`](https://docs.baseten.co/reference/sdk/loops/training-client) that resumes from `path` with the optimizer state and step count intact. The new run uses the checkpoint's base model and LoRA configuration. Use this to continue a run exactly where it left off. `replicas` works as in `create_lora_training_client`.

**create\_sampling\_client(base\_model=None, timeout=None, ready\_timeout=3600.0, model\_path=None, max\_seq\_len=None, num\_replicas=None, scope=None, record\_stability\_info=False)** `SamplingClient`

Create a standalone sampler and return a connected [`SamplingClient`](https://docs.baseten.co/reference/sdk/loops/sampling-client). A standalone sampler has no trainer or run behind it and receives no weight syncs. Loops places it in the serverless mode or on a sampler deployment. Pass exactly one of `base_model` or `model_path` (a `bt://loops:<run_id>/sampler_weights/<name>` checkpoint URI to serve); passing both or neither raises `ValueError`. For a sampler deployment, blocks until its deployment is `ACTIVE`. A serverless sampler has no deployment readiness check.

`max_seq_len` sets the longest prompt in tokens a sampler deployment must handle. Omit it and Loops picks the default for the model and the accelerators available to you. Serverless samplers ignore this setting and serve the sequence length serverless supports for the model.

`timeout` sets the read timeout for a single `sample()` call on the returned client. Omit it and `sample()` waits for the server. A dedicated sampler ends the request with a `504` after the platform's sampling timeout. A serverless request waits in the Loops queue until it finishes or Loops fails it, and then `sample()` raises [`RemoteOpError`](https://docs.baseten.co/reference/sdk/loops/errors). Pass a number of seconds to bound the wait, and `sample()` raises [`SampleTimeoutError`](https://docs.baseten.co/reference/sdk/loops/errors) when the wait exceeds it. Loops cancels a serverless request that hasn't started by then.

`num_replicas` sets the replica count for a standalone sampler in the dedicated mode, applied as both its minimum and maximum. Must be at least 1. Omit it and the backend default applies. Serverless samplers ignore this setting.

To sample from a live run's latest weights, use [`TrainingClient.save_weights_and_get_sampling_client`](https://docs.baseten.co/reference/sdk/loops/training-client) instead. `ServiceClient.local` clients don't support `model_path`.

`scope` selects the standalone sampler's [availability mode](https://docs.baseten.co/loops/availability-modes/overview.md#choose-a-mode), with the same values and environment-variable fallback as `create_lora_training_client()`.

A serverless standalone sampler also waits for room in that pool, and raises [`LoopsCapacityError`](https://docs.baseten.co/reference/sdk/loops/errors#param-loops-capacity-error) while it stays fully committed. See [capacity and quota errors](https://docs.baseten.co/troubleshooting/loops.md#resolve-capacity-and-quota-errors).

`record_stability_info=True` records every sample from the returned client and returns a `sequence_id` for each, for use with `Datum.with_provenance()`. For [router replay](https://docs.baseten.co/loops/router-replay.md), record from a run's sampling client instead, so the run's own sampler captures the routes.

**get\_server\_capabilities()** `ServerCapabilities`

Return the base models Loops supports and whether your workspace can train each one. Call it before `create_lora_training_client` to confirm your workspace can train a model and to find the longest sequence length you can use. Returns [`ServerCapabilities`](https://docs.baseten.co/reference/sdk/loops/types).

The SDK's typed model entries don't expose serverless availability. Use the [capabilities API](https://docs.baseten.co/reference/loops-api/server/get-capabilities.md) to inspect the `serverless` field in the HTTP response.

**list\_checkpoints(run\_id)** `list[Checkpoint]`

List checkpoints saved by the run identified by `run_id`. Calls the [list checkpoints API](https://docs.baseten.co/reference/loops-api/checkpoints/list-checkpoints.md), not the trainer directly. Returns a list of [`Checkpoint`](https://docs.baseten.co/reference/sdk/loops/types).

**get\_checkpoint(path)** `Checkpoint`

Look up the checkpoint saved at a `bt://` URI, such as a `SamplingClient.checkpoint_path`, and return its [`Checkpoint`](https://docs.baseten.co/reference/sdk/loops/types), including `base_model`. Raises `ValueError` if no checkpoint exists at `path`.

**get\_checkpoint\_archive\_url(checkpoint\_id=None, name=None, run\_id=None, target=None, page\_size=1000, page\_token=0)** `CheckpointFilesResponse`

Return presigned URLs for every file in an S3-backed checkpoint folder. Pass either `checkpoint_id` (a [`Checkpoint.id`](https://docs.baseten.co/reference/sdk/loops/types)) or `name` with `run_id`; `target` (a `CheckpointTarget`) picks one when a name was saved for both a trainer and a sampler checkpoint. The Loops stack writes checkpoints as unzipped directories rather than archives, so this returns a file list instead of a single archive URL. Volume-backed checkpoints can't be fetched by URL; use `download_checkpoint()` instead. Wraps the [get checkpoint files API](https://docs.baseten.co/reference/loops-api/checkpoints/get-checkpoint-files.md).

\**download\_checkpoint(checkpoint\_id=None, *, dest\_dir, name=None, run\_id=None, target=None)** `CheckpointDownload`

Download a checkpoint to a local directory, whether its files live in S3 or a Baseten volume. Pass either `checkpoint_id` (a [`Checkpoint.id`](https://docs.baseten.co/reference/sdk/loops/types)) or `name` with `run_id`; `target` (a `CheckpointTarget`) picks one when a name was saved for both a trainer and a sampler checkpoint.

`dest_dir` must be empty for an S3-backed checkpoint. A volume-backed checkpoint lands in a subdirectory under `dest_dir`, and that landing directory must be empty. The returned [`CheckpointDownload`](https://docs.baseten.co/reference/sdk/loops/types) reports the actual destination, file count, and bytes written.

**list\_runs()** `list[Run]`

List the runs this client created, active and inactive, by calling the [List runs](https://docs.baseten.co/reference/loops-api/runs/list-runs.md) API filtered to this client's session. Raises `RuntimeError` for a local client. Use it to find a run whose create request lost its response, so you can deactivate it.

**list\_samplers()** `list[Sampler]`

List the samplers this client created, active and inactive, by calling the [List samplers](https://docs.baseten.co/reference/loops-api/samplers/list-samplers.md) API filtered to this client's session. The list includes samplers paired to a run. Raises `RuntimeError` for a local client.

**deactivate\_run(run\_id)** `None`

Shut down a run and its paired sampler, which stops their billing. Saved checkpoints stay available. Succeeds if the run is already inactive. Same as `TrainingClient.deactivate()`, for a run you have no client for. Raises `RuntimeError` for a local client.

**deactivate\_sampler(sampler\_id)** `None`

Shut down a standalone sampler, which stops its billing. Succeeds if the sampler is already inactive. A sampler paired to a run returns a 409 error that names the run; deactivate the run instead. Same as `SamplingClient.deactivate()`, for a sampler you have no client for. Raises `RuntimeError` for a local client.

**session\_id** `str`

Property. The session ID assigned by the control plane. Available after construction.
